### Install OrcaUI via NPM or Yarn

Source: https://context7.com/orcasaga/orcaui/llms.txt

Install OrcaUI as a package for use with module bundlers and build systems.

```bash
# Install via npm
npm install orcaui

# Install via yarn
yarn add orcaui
```

--------------------------------

### OrcaUI Step Component Examples

Source: https://context7.com/orcasaga/orcaui/llms.txt

Use oc-step and oc-step-item to create progress indicators. Supports 'current', 'flipped', and 'inverted' states.

```html
<!-- Basic step indicator -->
<oc-step current="2">
  <oc-step-item title="Step 1" description="Account Setup"></oc-step-item>
  <oc-step-item title="Step 2" description="Personal Info"></oc-step-item>
  <oc-step-item title="Step 3" description="Confirmation"></oc-step-item>
</oc-step>

<!-- Flipped step layout -->
<oc-step current="1" flipped>
  <oc-step-item title="Start"></oc-step-item>
  <oc-step-item title="Process"></oc-step-item>
  <oc-step-item title="Complete"></oc-step-item>
</oc-step>

<!-- Inverted color scheme -->
<oc-step current="2" inverted>
  <oc-step-item title="Draft"></oc-step-item>
  <oc-step-item title="Review"></oc-step-item>
  <oc-step-item title="Published"></oc-step-item>
</oc-step>
```

--------------------------------

### Drawer Component Examples

Source: https://context7.com/orcasaga/orcaui/llms.txt

The oc-drawer component slides out panels from different sides. The 'bottom' placement automatically includes rounded top corners. Use the open() method to display the drawer.

```html
<oc-drawer id="rightDrawer" placement="right">
  <div slot="content">
    <h3>Settings</h3>
    <p>Drawer content here</p>
  </div>
</oc-drawer>

<!-- Bottom drawer with rounded corners -->
<oc-drawer id="bottomDrawer" placement="bottom">
  <div slot="content">
    <h3>Options</h3>
    <p>Bottom drawer automatically has rounded top corners</p>
  </div>
</oc-drawer>

<oc-btn onclick="document.querySelector('#rightDrawer').open()">
  Open Right Drawer
</oc-btn>

<oc-btn onclick="document.querySelector('#bottomDrawer').open()">
  Open Bottom Drawer
</oc-btn>
```

--------------------------------

### Import OrcaUI in JavaScript

Source: https://context7.com/orcasaga/orcaui/llms.txt

Import OrcaUI using ES Module, CommonJS, or UMD formats depending on your project setup.

```javascript
// ES Module import
import orca from 'orcaui/dist/js/orca.esm.js';

// CommonJS require
const orca = require('orcaui/dist/js/orca.cjs.js');

// UMD format (browser global)
// Available as window.orca after including orca.js
```

--------------------------------

### OrcaUI Buoy Component Examples

Source: https://context7.com/orcasaga/orcaui/llms.txt

The oc-buoy component displays notification badges or dot indicators. It can be 'flipped' and styled with CSS variables.

```html
<!-- Badge notification -->
<oc-buoy count="5">
  <oc-btn>Messages</oc-btn>
</oc-buoy>

<!-- Flipped buoy position -->
<oc-buoy count="3" flipped>
  <oc-icon name="bell"></oc-icon>
</oc-buoy>

<!-- Custom styled buoy using CSS variable -->
<oc-buoy count="99+" style="--_buoy-r: 12px;">
  <oc-btn>Notifications</oc-btn>
</oc-buoy>

<!-- Dot indicator without count -->
<oc-buoy dot>
  <oc-icon name="email"></oc-icon>
</oc-buoy>
```

--------------------------------

### Initialize Viewer Module

Source: https://context7.com/orcasaga/orcaui/llms.txt

Configures the image gallery viewer with specific tools and event callbacks.

```html
<div id="gallery">
  <img src="photo1.jpg" data-viewer alt="Photo 1">
  <img src="photo2.jpg" data-viewer alt="Photo 2">
  <img src="photo3.jpg" data-viewer alt="Photo 3">
</div>

<script>
// Initialize viewer
const viewer = new orca.Viewer('#gallery', {
  tools: orca.createTools(['zoomIn', 'zoomOut', 'rotate', 'download']),
  onView: (index, img) => {
    console.log('Viewing image:', index, img.src);
  }
});

// createTools accepts built-in tool names
const customTools = orca.createTools([
  'prev',
  'next',
  'zoomIn',
  'zoomOut',
  'fullscreen'
]);
</script>
```

--------------------------------

### Basic Popup and Dialog with Actions

Source: https://context7.com/orcasaga/orcaui/llms.txt

Use oc-popup for modal content and oc-dialog for confirmation dialogs. Dialogs support a footer slot for action buttons. Use the open() and close() methods to control visibility.

```html
<oc-popup id="myPopup">
  <div slot="content">
    <h3>Popup Title</h3>
    <p>This is popup content.</p>
  </div>
</oc-popup>

<oc-btn onclick="document.querySelector('#myPopup').open()">
  Open Popup
</oc-btn>
```

```html
<oc-dialog id="confirmDialog" title="Confirm Action">
  <p>Are you sure you want to proceed?</p>
  <div slot="footer">
    <oc-btn onclick="this.closest('oc-dialog').close()">Cancel</oc-btn>
    <oc-btn type="primary" onclick="confirmAction()">Confirm</oc-btn>
  </div>
</oc-dialog>
```

```javascript
function confirmAction() {
  console.log('Action confirmed');
  document.querySelector('#confirmDialog').close();
}
```

--------------------------------

### Use Utility Functions

Source: https://context7.com/orcasaga/orcaui/llms.txt

Provides helpers for DOM element selection, visibility detection, and date conversion.

```javascript
// Get single element (works inside template elements)
const element = orca.getEl('#myElement');
const templateChild = orca.getEl('.item', document.querySelector('template'));

// Get multiple elements (works inside template elements)
const elements = orca.getEls('.list-item');
const templateItems = orca.getEls('.item', document.querySelector('template'));

// Check if child is visible within scrollable parent
const parent = document.querySelector('.scroll-container');
const child = document.querySelector('.target-item');
const isVisible = orca.isChildVisible(parent, child);

console.log('Child is visible in parent:', isVisible);

// Convert various date formats to local time
const localTime = orca.toLocalTime('2025-07-26T10:30:00Z');
const localTime2 = orca.toLocalTime('July 26, 2025 10:30 AM');

console.log('Local time:', localTime);
```

--------------------------------

### Implement Datetime Component

Source: https://context7.com/orcasaga/orcaui/llms.txt

Configures date and time pickers with various formatting options and provides access to date utility tools.

```html
<!-- Basic date picker -->
<oc-datetime name="birthdate" format="YYYY-MM-DD"></oc-datetime>

<!-- US date format with week start on Sunday -->
<oc-datetime
  name="appointment"
  format="MM/DD/YYYY"
  headFormat="USA"
  weekStart="USA">
</oc-datetime>

<!-- Date with time and 12-hour format -->
<oc-datetime
  name="event"
  format="YYYY-MM-DD H:mm A"
  separator=";">
</oc-datetime>

<!-- Week number display -->
<oc-datetime
  name="schedule"
  format="YYYY-WW"
  showWeek>
</oc-datetime>

<script>
// Access date tools for programmatic date manipulation
const dateTools = orca.dateTools;

// Get ISO formatted date
const isoDate = dateTools.getIsoDate(new Date());

// Get year and week number
const yearWeek = dateTools.getYearWeek(new Date());

// Get 12-hour formatted time
const time12 = dateTools.get12Hour(new Date());

console.log(isoDate, yearWeek, time12);
</script>
```

--------------------------------

### Initialize Lazy Loading Module

Source: https://context7.com/orcasaga/orcaui/llms.txt

Implements lazy loading for images using Intersection Observer. Elements trigger loading when they partially enter the viewport.

```html
<!-- Lazy loaded images -->
<img data-lazy-src="image1.jpg" alt="Lazy image 1" class="lazy">
<img data-lazy-src="image2.jpg" alt="Lazy image 2" class="lazy">
<img data-lazy-src="image3.jpg" alt="Lazy image 3" class="lazy">

<script>
// Initialize lazy loading
const lazy = new orca.Lazy('.lazy', {
  rootMargin: '50px',
  threshold: 0.1, // Triggers when 10% of element is visible
  onLoad: (el) => {
    el.classList.add('loaded');
    console.log('Loaded:', el.dataset.lazySrc);
  }
});
</script>

<style>
.lazy {
  opacity: 0;
  transition: opacity 0.3s;
}
.lazy.loaded {
  opacity: 1;
}
</style>
```

--------------------------------

### Implement Search Component

Source: https://context7.com/orcasaga/orcaui/llms.txt

Configures search input fields with various styling options and event listeners for input and submission.

```html
<!-- Basic search input -->
<oc-search name="query" placeholder="Search..."></oc-search>

<!-- Rounded search with size -->
<oc-search
  name="search"
  shape="round"
  size="large"
  placeholder="Search products...">
</oc-search>

<!-- Notable search style -->
<oc-search
  name="filter"
  notable
  placeholder="Filter results...">
</oc-search>

<script>
const search = document.querySelector('oc-search');

search.addEventListener('input', (e) => {
  console.log('Search query:', e.target.value);
});

search.addEventListener('submit', (e) => {
  e.preventDefault();
  console.log('Searching for:', e.target.value);
});
</script>
```

--------------------------------

### Implement File Upload Component

Source: https://context7.com/orcasaga/orcaui/llms.txt

Configures file selection inputs with support for multiple files and custom localization labels.

```html
<!-- Single file upload -->
<oc-file name="document" accept=".pdf,.doc,.docx">
  <oc-btn>Select Document</oc-btn>
</oc-file>

<!-- Multiple file upload -->
<oc-file name="images" accept="image/*" multiple>
  <oc-btn>Select Images</oc-btn>
</oc-file>

<!-- Custom language labels -->
<oc-file
  name="files"
  multiple
  lang='{"hasFiles": "{count} files selected"}'>
  <oc-btn>Upload Files</oc-btn>
</oc-file>

<script>
const fileInput = document.querySelector('oc-file');

fileInput.addEventListener('change', (e) => {
  const files = e.target.files;
  console.log('Selected files:', files);
});
</script>
```

--------------------------------

### Basic and Multi-select Dropdowns

Source: https://context7.com/orcasaga/orcaui/llms.txt

Use oc-select for single or multiple item selections. Listen for the 'change' event to capture selected values.

```html
<oc-select name="country" placeholder="Select country">
  <oc-option value="us">United States</oc-option>
  <oc-option value="uk">United Kingdom</oc-option>
  <oc-option value="ca">Canada</oc-option>
</oc-select>
```

```html
<oc-select name="skills" multiple placeholder="Select skills">
  <oc-option value="js">JavaScript</oc-option>
  <oc-option value="css">CSS</oc-option>
  <oc-option value="html">HTML</oc-option>
</oc-select>
```

```javascript
const select = document.querySelector('oc-select');

select.addEventListener('change', (e) => {
  console.log('Selected value:', e.target.value);
});
```

--------------------------------

### Basic OrcaUI Button Component (Btn)

Source: https://context7.com/orcasaga/orcaui/llms.txt

Use the oc-btn tag for basic button functionality. Listen for click events using standard JavaScript.

```html
<!-- Basic button -->
<oc-btn>Click Me</oc-btn>

<!-- Button with selected state -->
<oc-btn selected>Selected Button</oc-btn>

<!-- Button variants -->
<oc-btn type="primary">Primary</oc-btn>
<oc-btn type="success">Success</oc-btn>
<oc-btn type="warning">Warning</oc-btn>
<oc-btn type="danger">Danger</oc-btn>

<!-- Button with icon -->
<oc-btn>
  <oc-icon name="save"></oc-icon>
  Save Document
</oc-btn>

<script>
// Listen to button events
document.querySelector('oc-btn').addEventListener('click', (e) => {
  console.log('Button clicked:', e.target);
});
</script>
```

--------------------------------

### Include OrcaUI via CDN

Source: https://context7.com/orcasaga/orcaui/llms.txt

Include OrcaUI's CSS and JavaScript files using CDN links in your HTML for immediate use.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>OrcaUI App</title>
  <!-- Include OrcaUI CSS -->
  <link rel="stylesheet" href="https://unpkg.com/orcaui@1.0.5/dist/css/orca.css">
</head>
<body>
  <!-- Your OrcaUI components here -->

  <!-- Include OrcaUI JavaScript -->
  <script src="https://unpkg.com/orcaui@1.0.5/dist/js/orca.js"></script>
</body>
</html>
```

--------------------------------

### Configure CSS Variables and Theme Toggling

Source: https://context7.com/orcasaga/orcaui/llms.txt

Defines global CSS custom properties for theming and provides a JavaScript function to toggle between light and dark modes.

```html
<style>
:root {
  /* Primary colors */
  --oc-primary: #1890ff;
  --oc-success: #52c41a;
  --oc-warning: #faad14;
  --oc-danger: #ff4d4f;

  /* Component-specific variables */
  --_buoy-r: 10px;

  /* Field styling */
  .oc-field {
    margin-bottom: 16px;
  }
}

/* Dark theme example */
[data-theme="dark"] {
  --oc-primary: #177ddc;
  --oc-bg: #141414;
  --oc-text: #ffffff;
}
</style>

<script>
// Toggle dark theme
function toggleTheme() {
  const html = document.documentElement;
  const isDark = html.getAttribute('data-theme') === 'dark';
  html.setAttribute('data-theme', isDark ? 'light' : 'dark');
}
</script>

<oc-btn onclick="toggleTheme()">Toggle Theme</oc-btn>
```

--------------------------------

### Implement Swipe Component

Source: https://context7.com/orcasaga/orcaui/llms.txt

Configures touch-enabled carousels with thumbnail association and programmatic navigation.

```html
<!-- Basic swipe carousel -->
<oc-swipe id="mainSwipe" flow="h" gap="10" divide="1">
  <oc-swipe-item><img src="slide1.jpg" alt="Slide 1"></oc-swipe-item>
  <oc-swipe-item><img src="slide2.jpg" alt="Slide 2"></oc-swipe-item>
  <oc-swipe-item><img src="slide3.jpg" alt="Slide 3"></oc-swipe-item>
</oc-swipe>

<!-- Swipe with thumbnail navigation -->
<oc-swipe id="thumbSwipe" thumb="#mainSwipe" slides="auto" gap="5">
  <oc-swipe-item><img src="thumb1.jpg"></oc-swipe-item>
  <oc-swipe-item><img src="thumb2.jpg"></oc-swipe-item>
  <oc-swipe-item><img src="thumb3.jpg"></oc-swipe-item>
</oc-swipe>

<script>
// Navigate to specific slide using toLocate method
const swipe = document.querySelector('#mainSwipe');
swipe.toLocate(2); // Go to slide index 2

// Custom total format
swipe.setAttribute('total', JSON.stringify({
  format: (current, total) => `${current} of ${total} slides`
}));
</script>
```

--------------------------------

### Configure Scroll Module

Source: https://context7.com/orcasaga/orcaui/llms.txt

Provides smooth scrolling with support for horizontal and vertical flow. Use the scrollTo method to programmatically navigate to a specific position.

```html
<div id="scrollContainer" style="height: 300px; overflow: auto;">
  <div id="scrollContent">
    <!-- Long content here -->
  </div>
</div>

<script>
const scroll = new orca.Scroll('#scrollContainer', {
  flow: 'v', // vertical scrolling (use 'h' for horizontal)
  smooth: true,
  onScroll: (position) => {
    console.log('Scroll position:', position);
  }
});

// Scroll to specific position
scroll.scrollTo(500);
</script>
```

--------------------------------

### Format Text and Numbers

Source: https://context7.com/orcasaga/orcaui/llms.txt

Handles text formatting for currency, numbers, and Pinyin phonetic notation using the oc-format component.

```html
<!-- Basic text formatting -->
<oc-format type="currency" value="1234.56"></oc-format>

<!-- Pinyin formatting (preserved when no commas/spaces) -->
<oc-format type="pinyin" value="北京"></oc-format>

<!-- Number formatting -->
<oc-format type="number" value="1234567" separator=","></oc-format>

<script>
const format = document.querySelector('oc-format');
console.log('Formatted value:', format.textContent);
</script>
```

--------------------------------

### Gesture Module for Touch and Mouse Input

Source: https://context7.com/orcasaga/orcaui/llms.txt

The orca.Gesture module handles touch and mouse gestures on a specified element, including zoom and pan. It supports image transformations like flipping.

```html
<div id="gestureArea" style="width: 400px; height: 400px; border: 1px solid #ccc;">
  <img src="photo.jpg" id="gestureImage" alt="Zoomable image">
</div>
```

```javascript
const gesture = new orca.Gesture('#gestureArea', {
  step: { value: 0.1 },
  onZoom: (scale) => {
    console.log('Current zoom scale:', scale);
  },
  onPan: (x, y) => {
    console.log('Pan position:', x, y);
  }
});

// Gesture works correctly even when image is flipped
const img = document.querySelector('#gestureImage');
img.style.transform = 'scaleX(-1)'; // Horizontal flip
// Gesture zoom still works correctly after flip
```

--------------------------------

### Implement Range Component

Source: https://context7.com/orcasaga/orcaui/llms.txt

Configures numeric slider inputs with horizontal or vertical orientation and event handling.

```html
<!-- Basic range slider -->
<oc-range
  name="volume"
  min="0"
  max="100"
  value="50"
  flow="h">
</oc-range>

<!-- Vertical range slider -->
<oc-range
  name="brightness"
  min="0"
  max="255"
  value="128"
  flow="v">
</oc-range>

<script>
const range = document.querySelector('oc-range');

// Listen for value changes
range.addEventListener('change', (e) => {
  console.log('New value:', e.target.value);
});

// Reset to initial value
range.reset();
</script>
```

--------------------------------

### Tags Input Management

Source: https://context7.com/orcasaga/orcaui/llms.txt

The oc-tags component allows managing lists of tags with add/remove functionality. Listen for the 'output' event for tag changes and use the 'updateCont' method for programmatic updates.

```html
<oc-tags name="keywords">
  <oc-tag value="javascript">JavaScript</oc-tag>
  <oc-tag value="webdev">Web Development</oc-tag>
</oc-tags>
```

```javascript
const tags = document.querySelector('oc-tags');

// Listen for output events when tags change
tags.addEventListener('output', (e) => {
  console.log('Current tags:', e.detail);
});

// Programmatically update content
tags.updateCont(['react', 'vue', 'angular']);
```

--------------------------------

### OrcaUI Icon Component Usage

Source: https://context7.com/orcasaga/orcaui/llms.txt

Render icons using the oc-icon tag, specifying the icon name. Icons can be flipped and colored using CSS variables.

```html
<!-- Basic icon usage -->
<oc-icon name="home"></oc-icon>
<oc-icon name="settings"></oc-icon>
<oc-icon name="user"></oc-icon>

<!-- Icon with flipped orientation -->
<oc-icon name="arrow" flipped="horizontal"></oc-icon>
<oc-icon name="arrow" flipped="vertical"></oc-icon>

<!-- Colored icons using CSS variables -->
<oc-icon name="heart" style="--icon-color: red;"></oc-icon>
<oc-icon name="star" style="--icon-color: gold;"></oc-icon>

<!-- Icon sizes -->
<oc-icon name="check" style="font-size: 24px;"></oc-icon>
<oc-icon name="check" style="font-size: 48px;"></oc-icon>
```

--------------------------------

### Implement Form Validation

Source: https://context7.com/orcasaga/orcaui/llms.txt

Handles form field validation with debounced timing and custom submit event listeners. Requires the Valid library and specific oc-field tags.

```html
<form id="myForm">
  <oc-field name="email" required pattern="email">
    <input type="email" placeholder="Enter email">
  </oc-field>

  <oc-field name="phone" required>
    <input type="tel" placeholder="Enter phone">
  </oc-field>

  <oc-btn type="submit">Submit</oc-btn>
</form>

<script>
const form = document.querySelector('#myForm');

// Initialize validation
const valid = new orca.Valid(form, {
  rules: {
    email: { required: true, pattern: orca.regExps.email },
    phone: { required: true, pattern: orca.regExps.phone }
  },
  onValid: (field, isValid) => {
    console.log(`${field} is ${isValid ? 'valid' : 'invalid'}`);
  }
});

// Listen for submit with validation
orca.validTools.listenSubmit(form, (data) => {
  console.log('Form submitted:', data);
});

// Parse field length for validation
const lengthInfo = orca.validTools.parseLength('username', 'Username', {
  min: 3, max: 20, value: 'test', label: 'Username'
});
</script>
```

--------------------------------

### Progress Bar Customization

Source: https://context7.com/orcasaga/orcaui/llms.txt

The oc-progress component displays progress bars. Customize value, max, width, and size. The 'value' attribute can be updated programmatically to show progress changes.

```html
<oc-progress value="75" max="100"></oc-progress>

<!-- Progress with custom width -->
<oc-progress value="50" max="100" width="300"></oc-progress>

<!-- Different sizes -->
<oc-progress value="25" size="small"></oc-progress>
<oc-progress value="50" size="medium"></oc-progress>
<oc-progress value="75" size="large"></oc-progress>
```

```javascript
const progress = document.querySelector('oc-progress');

// Update progress programmatically
let value = 0;
const interval = setInterval(() => {
  value += 10;
  progress.setAttribute('value', value);
  if (value >= 100) clearInterval(interval);
}, 500);
```

--------------------------------

### Validate Data with Regular Expressions

Source: https://context7.com/orcasaga/orcaui/llms.txt

Utilizes built-in regex patterns for common formats like email, phone, credit cards, and UUIDs.

```javascript
// Available regex patterns
const patterns = orca.regExps;

// Email validation
const isValidEmail = patterns.email.test('user@example.com');

// Phone validation
const isValidPhone = patterns.phone.test('+1-555-123-4567');

// Credit card validation (added in v1.0.3)
const isValidCard = patterns.creditCard.test('4111111111111111');

// UUID validation (added in v1.0.3)
const isValidUUID = patterns.uuid.test('550e8400-e29b-41d4-a716-446655440000');

// URL validation
const isValidURL = patterns.url.test('https://example.com');

console.log({
  email: isValidEmail,
  phone: isValidPhone,
  creditCard: isValidCard,
  uuid: isValidUUID,
  url: isValidURL
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.