@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Select.md

@@ -0,0 +1,284 @@
+---
+title: Select
+description: Styled native select component with validation, loading state, and form integration.
+package: "@g4rcez/components"
+export: "{ Select }"
+import: "import { Select } from '@g4rcez/components/select'"
+category: form
+---
+
+# Select
+
+Styled native select component with validation, loading state, and form integration.
+
+## Import
+
+```tsx
+import { Select } from "@g4rcez/components/select";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `OptionProps[]` | — | Array of option objects. |
+| `selectContainer` | `string` | `""` | Additional CSS classes for the select container. |
+| `required` | `boolean` | `true` | Whether the field is required. |
+| `error` | `string` | — | Error message to display. |
+| `loading` | `boolean` | `false` | Shows a loading indicator and disables the field. |
+| `disabled` | `boolean` | `false` | Disables the select. |
+| `placeholder` | `string` | — | Placeholder shown as a disabled hidden option. |
+| `value` | `string` | — | Controlled selected value. |
+| `onChange` | `(e: ChangeEvent<HTMLSelectElement>) => void` | — | Change handler. |
+| `...inputFieldProps` | `InputFieldProps` | — | All `InputField` props (title, left, right, feedback, etc.). |
+
+### OptionProps
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string` | Option value (required). |
+| `label` | `string` | Display text (falls back to `value` if omitted). |
+| `disabled` | `boolean` | Disables this individual option. |
+| `data-dynamic` | `string` | Marks a dynamically generated option. |
+| `data-*` | `string` | Any custom data attributes forwarded to the `<option>`. |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `text-foreground` | `--foreground` | Selected option text color |
+| `text-input-placeholder` | `--input-placeholder` | Color when no option is selected |
+| `placeholder-input-placeholder` | `--input-placeholder` | Placeholder styling |
+| `bg-input-mask-error` (via `group-error`) | `--input-mask-error` | Placeholder tint in error state |
+| `text-danger` (via `group-error`) | `--danger` | Text color in error state |
+| `hover:text-primary` | `--primary` | Caret icon hover color |
+| `h-input-height` | `--input-height` | Control height (2.5 rem) |
+| `px-input-x` | `--input-x` | Horizontal padding |
+| `py-input-y` | `--input-y` | Vertical padding |
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { useState } from "react";
+import { Select } from "@g4rcez/components/select";
+
+export default function FruitPicker() {
+  const [value, setValue] = useState("");
+
+  return (
+    <Select
+      title="Fruit"
+      options={[
+        { value: "apple", label: "Apple" },
+        { value: "banana", label: "Banana" },
+        { value: "orange", label: "Orange" },
+      ]}
+      placeholder="Select a fruit"
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
+```
+
+### With validation error
+
+```tsx
+import { useState } from "react";
+import { Select } from "@g4rcez/components/select";
+
+export default function CountrySelect() {
+  const [country, setCountry] = useState("");
+  const [error, setError] = useState("");
+
+  return (
+    <Select
+      title="Country"
+      options={[
+        { value: "us", label: "United States" },
+        { value: "ca", label: "Canada" },
+        { value: "uk", label: "United Kingdom" },
+      ]}
+      placeholder="Select country"
+      value={country}
+      error={error}
+      required
+      onChange={(e) => {
+        setCountry(e.target.value);
+        setError(e.target.value ? "" : "Please select a country");
+      }}
+    />
+  );
+}
+```
+
+### With disabled options
+
+```tsx
+import { Select } from "@g4rcez/components/select";
+
+export default function StatusSelect() {
+  return (
+    <Select
+      title="Status"
+      options={[
+        { value: "active", label: "Active" },
+        { value: "pending", label: "Pending" },
+        { value: "legacy", label: "Legacy (deprecated)", disabled: true },
+        { value: "inactive", label: "Inactive" },
+      ]}
+      placeholder="Select status"
+    />
+  );
+}
+```
+
+### Async options with loading state
+
+```tsx
+import { useEffect, useState } from "react";
+import { Select } from "@g4rcez/components/select";
+
+export default function AsyncSelect() {
+  const [options, setOptions] = useState<{ value: string; label: string }[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [value, setValue] = useState("");
+
+  useEffect(() => {
+    setLoading(true);
+    fetchOptions().then((data) => {
+      setOptions(data);
+      setLoading(false);
+    });
+  }, []);
+
+  return (
+    <Select
+      title="Region"
+      options={options}
+      placeholder={loading ? "Loading..." : "Select a region"}
+      value={value}
+      loading={loading}
+      disabled={loading}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
+```
+
+### Form integration with `useForm`
+
+```tsx
+import { Select } from "@g4rcez/components/select";
+import { useForm } from "@g4rcez/components/form";
+
+export default function UserForm() {
+  const form = useForm(schema, "userForm");
+
+  return (
+    <form {...form.props}>
+      <Select
+        {...form.select("role")}
+        options={[
+          { value: "admin", label: "Administrator" },
+          { value: "editor", label: "Editor" },
+          { value: "viewer", label: "Viewer" },
+        ]}
+        placeholder="Select role"
+      />
+    </form>
+  );
+}
+```
+
+### Cascading selects
+
+```tsx
+import { useState } from "react";
+import { Select } from "@g4rcez/components/select";
+
+const subcategories: Record<string, { value: string; label: string }[]> = {
+  electronics: [
+    { value: "phones", label: "Phones" },
+    { value: "laptops", label: "Laptops" },
+  ],
+  clothing: [
+    { value: "shirts", label: "Shirts" },
+    { value: "pants", label: "Pants" },
+  ],
+};
+
+export default function CascadingSelect() {
+  const [category, setCategory] = useState("");
+  const [subcategory, setSubcategory] = useState("");
+
+  return (
+    <div className="flex flex-col gap-base">
+      <Select
+        title="Category"
+        options={[
+          { value: "electronics", label: "Electronics" },
+          { value: "clothing", label: "Clothing" },
+        ]}
+        placeholder="Select category"
+        value={category}
+        onChange={(e) => {
+          setCategory(e.target.value);
+          setSubcategory("");
+        }}
+      />
+
+      {category && (
+        <Select
+          title="Subcategory"
+          options={subcategories[category] ?? []}
+          placeholder="Select subcategory"
+          value={subcategory}
+          onChange={(e) => setSubcategory(e.target.value)}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+## Do
+
+- Use descriptive `label` values for each option.
+- Order options logically (alphabetically or by usage frequency).
+- Provide a `placeholder` so users know what to select.
+- Use `loading` and `disabled` together while fetching options asynchronously.
+- Use design-token classes for wrapper elements (`bg-background`, `text-foreground`, `border-border`).
+
+## Don't
+
+- Don't use `Select` for only 2–3 options — prefer `Radiobox` or `Switch` for better visibility.
+- Don't use `Select` for large searchable lists — use `Autocomplete` instead.
+- Don't use long option labels that may truncate on small viewports.
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
+
+## Accessibility
+
+- Uses a native `<select>` element for full keyboard support and screen-reader compatibility.
+- The `placeholder` renders as a `disabled hidden` option so it is never submitted.
+- A `ChevronDownIcon` caret is rendered inside a `<label>` pointing to the select id, giving it a larger click target.
+- `data-selected` is set to `"false"` until the user selects an option, which toggles the placeholder color class.
+
+## Data Attributes
+
+| Attribute | Element | Value | Description |
+|-----------|---------|-------|-------------|
+| `data-component` | `InputField` root | `"select"` | Identifies the component. |
+| `data-selected` | `<select>` | `"true" \| "false"` | Whether a non-placeholder option is selected. |
+
+## Notes
+
+- Built on `InputField` for layout, label, error, and loading handling.
+- Supports all standard HTML `<select>` attributes via prop spread.
+- `required` defaults to `true` — pass `required={false}` when the field is optional.
+- Custom data attributes on `OptionProps` (e.g., `data-price`) are forwarded to each `<option>` and accessible via `e.target.selectedOptions[0].dataset`.

package/dist/ai/docs/Shortcut.md

@@ -0,0 +1,105 @@
+---
+title: Shortcut
+description: Inline keyboard shortcut display with automatic OS-specific key symbol mapping.
+package: "@g4rcez/components"
+export: "{ Shortcut }"
+import: "import { Shortcut } from '@g4rcez/components'"
+category: display
+---
+
+# Shortcut
+
+Inline keyboard shortcut display with automatic OS-specific key symbol mapping.
+
+## Import
+
+```tsx
+import { Shortcut } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | Shortcut string to display, e.g. `"Mod + K"` or `"Shift + Alt + P"` |
+
+## Design Tokens
+
+The `Shortcut` component inherits text color and size from its parent. No component-scoped tokens.
+
+## OS Mapping
+
+The component automatically maps keys based on the user's operating system:
+
+| Key token | macOS | Other |
+|-----------|-------|-------|
+| `Mod` | `⌘` (CommandIcon, `size={12}`) | `Ctrl` |
+| `Alt` | `⌥` (OptionIcon, `size={12}`) | `Alt` |
+
+All other key tokens are rendered as-is.
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Shortcut value="Mod + K" />
+```
+
+### In a Tooltip
+
+```tsx
+<Tooltip title="Save changes">
+  <div className="flex gap-2 items-center">
+    Save <Shortcut value="Mod + S" />
+  </div>
+</Tooltip>
+```
+
+### In a Command Palette Item
+
+```tsx
+<div className="flex items-center justify-between w-full">
+  <span>Open command palette</span>
+  <Shortcut value="Mod + K" />
+</div>
+```
+
+### Complex Multi-Key Shortcuts
+
+```tsx
+<Shortcut value="Shift + Alt + P" />
+<Shortcut value="Mod + Shift + L" />
+```
+
+### In a Menu Item
+
+```tsx
+<div className="flex items-center justify-between px-4 py-2">
+  <span className="text-foreground">New File</span>
+  <Shortcut value="Mod + N" />
+</div>
+```
+
+## Do
+
+- Use `"Mod"` instead of `"Ctrl"` or `"Cmd"` to get automatic platform-specific rendering.
+- Use `"Alt"` for the Option/Alt key — it also gets platform-specific rendering on macOS.
+- Place `Shortcut` next to the label of the action it accelerates (button, menu item, tooltip).
+
+## Don't
+
+- Don't hardcode platform symbols like `⌘` or `Ctrl` directly — let `Shortcut` handle the mapping.
+- Don't pass arbitrary Tailwind values (`text-[--my-var]`) for text color — let the component inherit from its parent.
+- Don't use `Shortcut` for descriptive text longer than a typical keyboard combination.
+
+## Accessibility
+
+- Each key segment renders inside a `<kbd>` element with an `aria-label` equal to the raw key name (e.g. `aria-label="Mod"`), so screen readers announce the semantic name regardless of the visual symbol.
+- Icon-based keys (`CommandIcon`, `OptionIcon`) also carry their own `aria-label` attribute.
+
+## Notes
+
+- The component renders a `<span>` with `flex items-center gap-1 text-sm`.
+- Keys are split on `"+"` and trimmed, so `"Mod + K"`, `"Mod+K"`, and `"Mod +K"` all produce the same output.
+- The OS check uses `isMac()` from the internal `combi-keys` utility, which reads `navigator.userAgent`.

package/dist/ai/docs/Skeleton.md

@@ -0,0 +1,166 @@
+---
+title: Skeleton
+description: Animated loading placeholder components for content that is being fetched.
+package: "@g4rcez/components"
+export: "{ Skeleton, SkeletonCell, SkeletonList }"
+import: "import { Skeleton, SkeletonCell, SkeletonList } from '@g4rcez/components'"
+category: display
+---
+
+# Skeleton
+
+Animated loading placeholder components for content that is being fetched.
+
+## Import
+
+```tsx
+import { Skeleton, SkeletonCell, SkeletonList } from "@g4rcez/components";
+```
+
+## Components
+
+### SkeletonCell
+
+A pre-built table-cell skeleton with `h-6 w-10/12 animate-pulse rounded bg-muted`. Renders as a plain `<div>` (no props).
+
+### Skeleton
+
+A configurable block skeleton.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Override or extend dimensions and shape |
+| `as` | `React.ElementType` | `"span"` | Polymorphic root element |
+| `style` | `CSSProperties` | — | Inline styles (e.g. dynamic `width`) |
+
+Default appearance: `block h-8 w-32 animate-pulse rounded bg-muted`.
+
+### SkeletonList
+
+A vertical list of randomized-width `Skeleton` lines.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `rows` | `number` | — | Number of skeleton lines to render |
+| `className` | `string` | — | Additional classes for the `<ul>` container |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-muted` | `--muted` | Pulse animation background for all skeleton variants |
+
+## Examples
+
+### Table Loading Skeleton
+
+```tsx
+function TableSkeleton() {
+  return (
+    <table className="w-full">
+      <tbody>
+        {Array.from({ length: 5 }).map((_, index) => (
+          <tr key={index} className="border-b border-border">
+            <td className="py-3 px-4"><SkeletonCell /></td>
+            <td className="py-3 px-4"><SkeletonCell /></td>
+            <td className="py-3 px-4"><SkeletonCell /></td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+### Card Loading Skeleton
+
+```tsx
+function CardSkeleton() {
+  return (
+    <div className="rounded-card border border-card-border bg-card-background p-6 space-y-4">
+      <Skeleton className="h-4 w-3/4" />
+      <div className="space-y-2">
+        <SkeletonCell />
+        <SkeletonCell />
+        <Skeleton className="h-2 w-1/2" />
+      </div>
+      <div className="flex gap-2">
+        <Skeleton className="h-8 w-20" />
+        <Skeleton className="h-8 w-16" />
+      </div>
+    </div>
+  );
+}
+```
+
+### List Loading Skeleton
+
+```tsx
+<SkeletonList rows={5} className="px-4" />
+```
+
+### Conditional Skeleton
+
+```tsx
+function DataSection({ data, loading }: { data?: Item; loading: boolean }) {
+  return (
+    <div>
+      {loading ? (
+        <Skeleton className="h-6 w-full" />
+      ) : (
+        <p>{data?.name}</p>
+      )}
+    </div>
+  );
+}
+```
+
+### Avatar + Text Row Skeleton
+
+```tsx
+function UserRowSkeleton() {
+  return (
+    <div className="flex items-center gap-3">
+      <Skeleton className="size-10 rounded-full" />
+      <div className="flex-1 space-y-1">
+        <SkeletonCell />
+        <Skeleton className="h-2 w-1/3" />
+      </div>
+    </div>
+  );
+}
+```
+
+## Do
+
+- Design skeletons that closely match the dimensions of the real content to minimize layout shift.
+- Use `animate-pulse` (applied by default) to signal that the system is active.
+- Use `SkeletonList` for simple vertically stacked text content.
+- Wrap skeleton containers with `aria-live="polite"` so screen readers announce when real content loads.
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-gray-200`, `bg-slate-300`) as `className` — use `bg-muted` or other design-token classes instead.
+- Don't use arbitrary Tailwind values (`bg-[#ddd]`) — override CSS variables in your `@theme` block.
+- Don't show skeletons for very short loading states (under ~300 ms) — it causes visual flicker.
+- Don't make skeletons too detailed; simple geometric shapes are most effective.
+- Don't use skeletons for error states — show `Empty` or `Alert` instead.
+
+## Accessibility
+
+- Skeleton components are purely decorative; they carry no ARIA roles.
+- Add `aria-live="polite"` to the container that transitions from skeleton to real content so assistive technologies announce the change.
+- Consider `aria-label="Loading content"` on the skeleton container for additional context.
+
+```tsx
+<div aria-live="polite">
+  {loading ? <SkeletonCell /> : <ActualContent />}
+</div>
+```
+
+## Notes
+
+- `SkeletonList` generates random widths at mount time (via `Math.random()`) so each row looks distinct. Widths are stable across re-renders thanks to `useRef`.
+- `Skeleton` uses `as="span"` by default, making it safe to use inside inline contexts. Change `as` to `"div"` or `"li"` as needed.

package/dist/ai/docs/Slider.md

@@ -0,0 +1,144 @@
+---
+title: Slider
+description: Accessible range input for selecting one or more numeric values along a scale.
+package: "@g4rcez/components"
+export: "{ Slider }"
+import: "import { Slider } from '@g4rcez/components'"
+category: form
+---
+
+# Slider
+
+Accessible range input for selecting one or more numeric values along a scale.
+
+## Import
+
+```tsx
+import { Slider } from "@g4rcez/components";
+```
+
+## Props
+
+`Slider` accepts all props from `@base-ui/react/slider` Root, plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tooltip` | `boolean` | `false` | Shows a tooltip with the current value above the thumb while dragging. |
+| `value` | `number[]` | — | Controlled value(s). |
+| `defaultValue` | `number[]` | `[0]` | Initial value(s) for uncontrolled usage. |
+| `min` | `number` | `0` | Minimum value. |
+| `max` | `number` | `100` | Maximum value. |
+| `step` | `number` | `1` | Increment between selectable values. |
+| `className` | `string` | — | Additional classes applied to the control track wrapper. |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-background` | `--background` | Track background (unfilled area) |
+| `bg-primary` | `--primary` | Indicator fill (filled area) |
+| `border-input-border` | `--input-border` | Thumb border color |
+| `bg-input-switch` | `--input-switch` | Thumb fill color (checked/active) |
+| `focus-within:ring-primary` | `--primary` | Focus ring on thumb |
+
+## Variants
+
+### Single thumb
+
+One value in `defaultValue` renders a single draggable thumb.
+
+### Range (dual thumb)
+
+Two values in `defaultValue` render two thumbs that define a range.
+
+## Examples
+
+### Single value
+
+```tsx
+import { Slider } from "@g4rcez/components";
+
+export default function VolumeControl() {
+  return (
+    <Slider
+      min={0}
+      max={100}
+      defaultValue={[50]}
+      onChange={(value) => console.log(value)}
+    />
+  );
+}
+```
+
+### Range slider
+
+```tsx
+import { Slider } from "@g4rcez/components";
+
+export default function PriceRangeFilter() {
+  return (
+    <Slider
+      min={0}
+      max={1000}
+      defaultValue={[200, 800]}
+      tooltip
+    />
+  );
+}
+```
+
+### Controlled with tooltip and custom step
+
+```tsx
+import { useState } from "react";
+import { Slider } from "@g4rcez/components";
+
+export default function SteppedSlider() {
+  const [value, setValue] = useState([0.5]);
+
+  return (
+    <div className="flex flex-col gap-base">
+      <Slider
+        min={0}
+        max={1}
+        step={0.1}
+        value={value}
+        tooltip
+        onValueChange={setValue}
+      />
+      <span className="text-sm text-muted-foreground">
+        Current: {value[0].toFixed(1)}
+      </span>
+    </div>
+  );
+}
+```
+
+## Do
+
+- Provide visible labels or descriptive context indicating what the slider controls.
+- Use `tooltip` for precise numeric adjustments where the exact value matters.
+- Use `step` to restrict selection to valid increments (e.g., `step={10}` for percentages in tens).
+- Use design-token classes for any wrapper elements (`bg-background`, `text-foreground`).
+
+## Don't
+
+- Don't use `Slider` for very large or effectively infinite ranges where a text `Input` would be more efficient.
+- Don't use `Slider` for selecting from a small discrete set (e.g., 3 named options) — use `Radiobox` or `Select`.
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `border-gray-300`) — use design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block instead.
+
+## Accessibility
+
+- Fully accessible via keyboard: Arrow keys increment/decrement the focused thumb.
+- Each thumb exposes `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`.
+- Touch targets for thumbs are sized generously (`size-5`) for mobile usability.
+- Compatible with screen readers through the underlying `@base-ui/react/slider`.
+
+## Notes
+
+- Built on `@base-ui/react/slider` — most structural ARIA and keyboard behavior comes from that primitive.
+- The `Thumb` sub-component observes `aria-valuenow` mutations via a `MutationObserver` to keep the tooltip value in sync without additional state.
+- Locale-aware: the `useLocale` hook is used internally for number formatting in tooltips.