@smilodon/core 1.4.12 → 1.5.0

package/README.md

@@ -20,9 +20,10 @@ Additional references:
 - **Performance Runbook**: [`docs/PERFORMANCE-RUNBOOK.md`](../../docs/PERFORMANCE-RUNBOOK.md)
 - **Performance Guide**: [`docs/PERFORMANCE.md`](../../docs/PERFORMANCE.md)
 - **Known Limitations**: [`docs/KNOWN-LIMITATIONS.md`](../../docs/KNOWN-LIMITATIONS.md)
+- **Build Tool Integration**: [`docs/BUILD-TOOL-INTEGRATION.md`](../../docs/BUILD-TOOL-INTEGRATION.md)
 
 The complete guide includes:
-- ✅ All 60+ CSS variables for complete customization
+- ✅ Complete styling token coverage for colors, layout, chips, motion, and accessibility
 - ✅ Vanilla JavaScript patterns (DOM manipulation, event listeners)
 - ✅ Complete API reference with all properties and methods
 - ✅ CDN usage and module bundler integration
@@ -702,18 +703,20 @@ enhanced-select.dark-mode {
 --select-dark-group-header-bg    /* Dark header background */
 ```
 
-**Complete CSS Variables List (60+ variables)**
+**Complete CSS Variables Reference**
 
-See the [full CSS variables reference](https://github.com/navidrezadoost/smilodon/blob/main/CHANGELOG.md#135---2026-02-09) for all 60+ customizable properties including:
-- Input container (gap, padding, height, borders, focus states)
-- Input field (width, padding, font, colors)
-- Arrow/icon (size, color, hover states, position)
-- **Separator line** (width, height, gradient, position)
-- **Selection badges** (padding, colors, **remove/delete button**)
-- Dropdown (margins, max-height, borders, shadows)
-- Options (font size, line height, borders, transitions)
-- Load more button (padding, borders, colors, hover states)
-- Loading/empty states (padding, colors, backgrounds, spinner)
+The canonical styling inventory now lives in:
+
+- [docs/STYLING.md](../../docs/STYLING.md) for strategy and examples
+- [docs/STYLING-TOKENS.md](../../docs/STYLING-TOKENS.md) for the exhaustive token table
+
+That reference covers:
+
+- Theme foundation tokens (palette, shadows, radii, timing)
+- Input shell, separator, arrow, and clear-control hooks
+- Multi-select chip structure, remove-button states, and badge motion
+- Dropdown, scrollbar, group-header, and option-state hooks
+- Empty, loading, searching, error, reduced-motion, and high-contrast hooks
 
 #### Highlighted Customization Features
 
@@ -747,6 +750,85 @@ enhanced-select {
 **Gradient Dropdown + Hover/Selected States**
 If your dropdown uses a gradient background (for example via `--select-dropdown-bg`), option hover/selected colors still work as expected. The component intentionally uses the `background` shorthand for hover/selected option states so any inherited `background-image` layers are cleared correctly.
 
+**Closed Input Value + Dropdown Option Alignment**
+You can switch alignment and inspect both the selected value in the closed input and the dropdown options with matching tokens:
+
+```css
+enhanced-select.align-center {
+  --select-input-text-align: center;
+  --select-option-text-align: center;
+}
+
+enhanced-select.align-right {
+  --select-input-text-align: right;
+  --select-option-text-align: right;
+}
+```
+
+Useful related hooks:
+
+- `--select-input-text-align`
+- `--select-input-justify-content`
+- `--select-option-text-align`
+- `--select-group-header-text-align`
+
+This is especially useful when testing centered or right-aligned UI layouts, because you can verify the closed state and open dropdown state together.
+
+**Dropdown Placement: Bottom / Top / Automatic**
+The dropdown can be opened in three modes:
+
+- `bottom` — always below the select
+- `top` — always above the select
+- `auto` — below if there is enough room below, otherwise above
+
+Per-instance:
+
+```ts
+select.updateConfig({
+  dropdownPlacement: {
+    mode: 'auto',
+  },
+});
+```
+
+Global default:
+
+```ts
+configureSelect({
+  dropdownPlacement: {
+    mode: 'top',
+  },
+});
+```
+
+Related styling hooks:
+
+- `--select-dropdown-top`
+- `--select-dropdown-bottom`
+- `--select-dropdown-transform-origin`
+- `--select-dropdown-top-transform-origin`
+
+**Direction: LTR / RTL**
+The select supports both `ltr` and `rtl` directions. The default is `ltr`.
+
+Global default:
+
+```ts
+configureSelect({
+  direction: 'rtl',
+});
+```
+
+Per-instance:
+
+```ts
+select.updateConfig({
+  direction: 'rtl',
+});
+```
+
+RTL support mirrors the shell and dropdown layout, including arrow placement, clear control placement, separator side, selected indicator side, and chip remove spacing. The host `dir` attribute is kept in sync automatically.
+
 **Badge Remove/Delete Button (Multi-Select)**
 The × button that removes selected items in multi-select mode is fully customizable:
 
@@ -759,10 +841,15 @@ enhanced-select {
   /* Customize badge appearance */
   --select-badge-bg: #10b981;              /* Badge background */
   --select-badge-color: white;             /* Badge text color */
+  --select-badge-width: auto;              /* Explicit badge width */
+  --select-badge-height: 32px;             /* Explicit badge height */
   --select-badge-padding: 6px 10px;        /* Badge spacing */
+  --select-badge-margin: 4px;              /* Badge outer spacing */
+  --select-badge-border-radius: 10px;      /* Badge radius */
   
   /* Customize the × (remove/delete) button */
   --select-badge-remove-size: 18px;        /* Button size */
+  --select-badge-remove-icon-size: 12px;   /* Icon glyph / SVG size */
   --select-badge-remove-bg: rgba(255, 255, 255, 0.3);  /* Button background */
   --select-badge-remove-color: white;      /* × symbol color */
   --select-badge-remove-font-size: 18px;   /* × symbol size */
@@ -770,6 +857,30 @@ enhanced-select {
 }
 ```
 
+You can also replace the default `×` with custom SVG or text:
+
+```ts
+select.updateConfig({
+  selection: {
+    removeButtonIcon: '<svg viewBox="0 0 16 16" fill="none"><path d="M4 4L12 12M12 4L4 12" stroke="currentColor" stroke-width="1.75" stroke-linecap="round"/></svg>'
+  }
+});
+```
+
+Runtime style config now also supports higher-level sections for:
+
+- `badge`
+- `badgeHover`
+- `badgeActive`
+- `badgeLabel`
+- `badgeRemove`
+- `badgeRemoveHover`
+- `badgeRemoveActive`
+- `groupHeader`
+- `activeOption`
+
+This means badge size, badge radius, remove-button size, group-header layout, and active-option border/radius can be controlled either with CSS tokens or with `updateConfig({ styles: ... })`.
+
 #### Real-World Customization Examples
 
 **Example 1: Bootstrap-style Select**
@@ -778,7 +889,7 @@ enhanced-select {
   --select-input-border: 1px solid #ced4da;
   --select-input-border-radius: 0.375rem;
   --select-input-focus-border: #86b7fe;
-  --select-input-focus-shadow: 0 0 0 0.25rem rgba(13, 110, 253, 0.25);
+  --select-shadow-focus: 0 0 0 0.25rem rgba(13, 110, 253, 0.25);
   --select-option-hover-bg: #e9ecef;
   --select-option-selected-bg: #0d6efd;
   --select-option-selected-color: white;
@@ -791,7 +902,7 @@ enhanced-select {
 enhanced-select {
   --select-input-border-radius: 4px;
   --select-input-focus-border: #1976d2;
-  --select-input-focus-shadow: none;
+  --select-shadow-focus: none;
   --select-option-padding: 16px;
   --select-option-hover-bg: rgba(0, 0, 0, 0.04);
   --select-option-selected-bg: #e3f2fd;
@@ -807,7 +918,7 @@ enhanced-select {
   --select-input-border: 1px solid #e5e7eb;
   --select-input-border-radius: 0.5rem;
   --select-input-focus-border: #3b82f6;
-  --select-input-focus-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+  --select-shadow-focus: 0 0 0 3px rgba(59, 130, 246, 0.1);
   --select-option-padding: 0.5rem 0.75rem;
   --select-option-hover-bg: #f3f4f6;
   --select-option-selected-bg: #dbeafe;
@@ -815,6 +926,8 @@ enhanced-select {
 }
 ```
 
+Framework compatibility guidance also lives in [../../docs/CSS-FRAMEWORK-COMPATIBILITY.md](../../docs/CSS-FRAMEWORK-COMPATIBILITY.md).
+
 **Example 4: Custom Brand Colors**
 ```css
 enhanced-select {