@sableui/react 0.6.2 → 0.7.1

package/dist/components/notification-badge/notification-badge.meta.js

@@ -0,0 +1,107 @@
+// src/components/notification-badge/notification-badge.meta.ts
+var notificationBadgeMeta = {
+  name: "NotificationBadge",
+  summary: `An unread indicator. Renders a bare dot or a count pill (capped as "{max}+"), or nothing when there's nothing to show. overlay pins it to the corner of a relative host; it is aria-hidden, so the host's name carries the count.`,
+  status: "stable",
+  keywords: [
+    "notification",
+    "badge",
+    "count",
+    "unread"
+  ],
+  usage: {
+    description: "Use NotificationBadge to show a compact unread count, alert count, or attention marker.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Place it on or near the item that owns the notifications."
+      },
+      {
+        guidance: "do",
+        description: "Use compact counts and cap large numbers when exact precision is not useful."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use NotificationBadge as a standalone status label or category marker."
+      },
+      {
+        guidance: "dont",
+        description: 'Do not show a bare dot when the count is meaningful. A dot says "something"; if the user can act on "how many", show the number.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not put a neutral badge on a secondary host. Both are the secondary surface, so the badge disappears; use primary or destructive there."
+      }
+    ]
+  },
+  related: {
+    components: ["Badge", "StatusDot"]
+  },
+  props: [
+    {
+      name: "dot",
+      type: "boolean",
+      default: "false",
+      description: "Render a bare dot indicator with no number. Takes precedence over count."
+    },
+    {
+      name: "count",
+      type: "number",
+      description: "Unread count. Renders nothing when <= 0 and dot is unset."
+    },
+    {
+      name: "max",
+      type: "number",
+      default: "99",
+      description: 'Cap before showing "{max}+".'
+    },
+    {
+      name: "tone",
+      type: '"destructive" | "primary" | "neutral"',
+      default: '"destructive"',
+      description: "Fill color. destructive for alarming counts; primary/neutral for non-alarming ones."
+    },
+    {
+      name: "size",
+      type: '"sm" | "md" | "lg"',
+      default: '"md"',
+      description: "Scales the dot/pill on the spacing scale (count pill: sm 16px, md 18px, lg 20px at the default density)."
+    },
+    {
+      name: "overlay",
+      type: "boolean",
+      default: "false",
+      description: "Pin to the top-end corner of the nearest relative host (an icon button) \u2014 one placement for every caller instead of hand-tuned absolute offsets."
+    }
+  ],
+  variants: {
+    tone: ["destructive", "primary", "neutral"],
+    size: ["sm", "md", "lg"],
+    overlay: ["true", "false"]
+  },
+  tokensUsed: [
+    "destructive",
+    "destructive-foreground",
+    "primary",
+    "primary-foreground",
+    "secondary",
+    "secondary-foreground"
+  ],
+  a11y: [
+    'The badge is aria-hidden: a count rendered on a control is not associated with it, so the host needs an accessible name that includes the count \u2014 "Notifications, 3 unread" \u2014 or a screen-reader user hears "Notifications, button" and never learns there is anything new. Pass aria-hidden={false} only for a standalone badge whose number is the information.',
+    "A dot carries no number and no words: on its own it tells a sighted user only that something changed, and tells everyone else nothing. Pair it with a label that says what is new, and never make its colour the only difference between two states."
+  ],
+  examples: [
+    {
+      label: "Dot + counts",
+      code: "<Row gap={3}><NotificationBadge dot /><NotificationBadge count={3} /><NotificationBadge count={128} /></Row>"
+    },
+    {
+      label: "Overlay on an icon button",
+      code: '<Button variant="secondary" size="icon" aria-label="Notifications, 5 unread" className="relative"><Icon name="bell" /><NotificationBadge count={5} overlay /></Button>'
+    }
+  ]
+};
+export {
+  notificationBadgeMeta
+};

package/dist/components/notification-badge/notification-badge.variants.js

@@ -0,0 +1,57 @@
+// src/components/notification-badge/notification-badge.variants.ts
+import { cva } from "class-variance-authority";
+var notificationDotVariants = cva("inline-block rounded-full", {
+  variants: {
+    tone: {
+      destructive: "bg-destructive",
+      primary: "bg-primary",
+      neutral: "bg-muted-foreground"
+      // StatusDot's neutral, so the two dots are one grey
+    },
+    size: {
+      sm: "size-1.5",
+      md: "size-2",
+      lg: "size-2.5"
+    },
+    // A dot is small enough to sit inside the corner; a count straddles it.
+    overlay: {
+      true: "absolute end-1 top-1",
+      false: ""
+    }
+  },
+  defaultVariants: {
+    tone: "destructive",
+    size: "md",
+    overlay: false
+  }
+});
+var notificationCountVariants = cva(
+  "inline-flex items-center justify-center rounded-full px-1 text-label-xs",
+  {
+    variants: {
+      tone: {
+        destructive: "bg-destructive text-destructive-foreground",
+        primary: "bg-primary text-primary-foreground",
+        neutral: "bg-secondary text-secondary-foreground"
+      },
+      size: {
+        sm: "h-4 min-w-4",
+        md: "h-4.5 min-w-4.5",
+        lg: "h-5 min-w-5"
+      },
+      overlay: {
+        true: "absolute -end-0.5 -top-0.5",
+        false: ""
+      }
+    },
+    defaultVariants: {
+      tone: "destructive",
+      size: "md",
+      overlay: false
+    }
+  }
+);
+export {
+  notificationCountVariants,
+  notificationDotVariants
+};

package/dist/components/number-field/index.js

@@ -0,0 +1,7 @@
+// src/components/number-field/index.ts
+import { NumberField } from "./number-field.js";
+import { numberFieldMeta } from "./number-field.meta.js";
+export {
+  NumberField,
+  numberFieldMeta
+};

package/dist/components/number-field/number-field.js

@@ -0,0 +1,70 @@
+// src/components/number-field/number-field.tsx
+import { NumberField as Base } from "@base-ui/react/number-field";
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { useDensity, useTypeTier } from "../../lib/density.js";
+import { FIELD_SHELL, MOBILE_FIELD_TIER } from "../../lib/field-shell.js";
+import { Button } from "../button/button.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function NumberField({
+  className,
+  steppers = true,
+  "aria-describedby": ariaDescribedby,
+  "aria-invalid": ariaInvalid,
+  "aria-label": ariaLabel,
+  ...root
+}) {
+  const step = /* @__PURE__ */ jsx(
+    Button,
+    {
+      variant: "ghost",
+      size: "icon-sm",
+      className: "mx-[calc((var(--control-md)-var(--control-sm)-2px)/2)] shrink-0 self-center text-muted-foreground"
+    }
+  );
+  const tier = useTypeTier();
+  const density = useDensity();
+  return /* @__PURE__ */ jsx(Base.Root, { ...root, children: /* @__PURE__ */ jsxs(
+    Base.Group,
+    {
+      className: cn(
+        "inline-flex h-(--control-md) w-full items-stretch overflow-hidden text-foreground",
+        // The shell Input wears — lib/field-shell. Its focus ring keys on
+        // focus-visible; the shell here is a group, so ring on focus-within.
+        FIELD_SHELL,
+        "focus-within:ring-2 focus-within:ring-ring",
+        "has-[input:disabled]:cursor-not-allowed has-[input:disabled]:opacity-50",
+        // FIELD_INVALID, lifted to the group: `aria-invalid` lands on the
+        // inner <input> (a Field sets it there), and a group role cannot
+        // carry it, so the shell reads it with `has-`. Literal for the
+        // Tailwind scan; keep in step with lib/field-shell.
+        "has-[input[aria-invalid=true]]:border-destructive has-[input[aria-invalid=true]]:ring-destructive/30",
+        tier.body,
+        density === "comfortable" && MOBILE_FIELD_TIER,
+        className
+      ),
+      children: [
+        steppers ? /* @__PURE__ */ jsx(Base.Decrement, { "aria-label": "Decrease", render: step, children: /* @__PURE__ */ jsx(Icon, { name: "minus" }) }) : null,
+        /* @__PURE__ */ jsx(
+          Base.Input,
+          {
+            "aria-describedby": ariaDescribedby,
+            "aria-invalid": ariaInvalid,
+            "aria-label": ariaLabel,
+            className: cn(
+              "w-full min-w-0 bg-transparent tabular-nums outline-none",
+              // Centred between two steppers; left-aligned without them, on
+              // Input's px-3 text column so a stack of fields shares one edge.
+              steppers ? "px-2 text-center" : "px-3 text-left"
+            )
+          }
+        ),
+        steppers ? /* @__PURE__ */ jsx(Base.Increment, { "aria-label": "Increase", render: step, children: /* @__PURE__ */ jsx(Icon, { name: "plus" }) }) : null
+      ]
+    }
+  ) });
+}
+NumberField.displayName = "NumberField";
+export {
+  NumberField
+};

package/dist/components/number-field/number-field.meta.js

@@ -0,0 +1,109 @@
+// src/components/number-field/number-field.meta.ts
+var numberFieldMeta = {
+  name: "NumberField",
+  summary: "Numeric input with decrement/increment steppers over Base UI NumberField \u2014 keyboard arrows, scroll, scrub-to-change, min/max clamping, locale formatting, and form integration. Styled like Input; drops straight into a Field.",
+  status: "stable",
+  keywords: [
+    "number field",
+    "numeric input",
+    "stepper",
+    "form"
+  ],
+  usage: {
+    description: "Use NumberField for numeric values that benefit from validation, min/max bounds, or step controls.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it for quantities, thresholds, percentages, and other real numeric values."
+      },
+      {
+        guidance: "do",
+        description: "Set sensible min, max, and step behavior when the domain has bounds."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use NumberField for identifiers such as phone numbers, ZIP codes, or credit card numbers."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it in a property grid with steppers left on. Its two 32px stepper buttons (36px each with their inset) put a ~110px floor on a control that needs ~44px there \u2014 pass steppers={false}, or use ScrubField."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Input",
+      "Slider"
+    ]
+  },
+  props: [
+    {
+      name: "min",
+      type: "number",
+      description: "Lower bound. Clamps typing, arrows, scroll and scrub alike, so the value cannot leave the range by any route."
+    },
+    {
+      name: "max",
+      type: "number",
+      description: "Upper bound, clamped on every input route the same way as `min`."
+    },
+    {
+      name: "value / defaultValue",
+      type: "number",
+      description: "Controlled / uncontrolled numeric value."
+    },
+    {
+      name: "onValueChange",
+      type: "(value: number | null, event) => void",
+      description: "Fired when the value changes (null when cleared)."
+    },
+    {
+      name: "step / smallStep / largeStep",
+      type: "number",
+      description: "Increment amount; smallStep applies with the meta key, largeStep with shift."
+    },
+    {
+      name: "format",
+      type: "Intl.NumberFormatOptions",
+      description: "Locale formatting (currency, percent, units, \u2026)."
+    },
+    {
+      name: "steppers",
+      type: "boolean",
+      default: "true",
+      description: "Show the decrement / increment buttons. Turn off in a dense property grid \u2014 the two 32px stepper buttons (36px with their inset) put a ~110px floor on the control; without them the value left-aligns."
+    },
+    {
+      name: "disabled / readOnly / required / name / id",
+      type: "\u2014",
+      description: "Standard form-control props. Base UI applies id + required to the input, so it labels and validates correctly."
+    }
+  ],
+  tokensUsed: [
+    "input",
+    "card",
+    "foreground",
+    "muted-foreground",
+    "accent",
+    "accent-foreground",
+    "ring"
+  ],
+  a11y: [
+    "Decrement / Increment are labelled buttons (Decrease / Increase); the input is a spinbutton with aria-valuenow/min/max from Base UI.",
+    "Routes aria-describedby / aria-invalid onto the input, so a Field's helper + error are announced for it."
+  ],
+  examples: [
+    { label: "Bounded", code: "<NumberField defaultValue={1} min={0} max={99} />" },
+    {
+      label: "In a field",
+      code: '<Field label="Quantity"><NumberField min={1} defaultValue={1} /></Field>'
+    },
+    {
+      label: "Currency",
+      code: '<NumberField defaultValue={9.99} format={{ style: "currency", currency: "USD" }} />'
+    }
+  ]
+};
+export {
+  numberFieldMeta
+};

package/dist/components/otp-field/index.js

@@ -0,0 +1,7 @@
+// src/components/otp-field/index.ts
+import { OtpField } from "./otp-field.js";
+import { otpFieldMeta } from "./otp-field.meta.js";
+export {
+  OtpField,
+  otpFieldMeta
+};

package/dist/components/otp-field/otp-field.js

@@ -0,0 +1,70 @@
+// src/components/otp-field/otp-field.tsx
+import * as OtpParts from "@base-ui/react/otp-field";
+import { Fragment } from "react";
+import { cn } from "../../lib/cn.js";
+import { FIELD_INVALID, FIELD_SHELL } from "../../lib/field-shell.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var resolvedBase;
+function otpBase() {
+  if (!resolvedBase) {
+    const otpExports = Object.fromEntries(Object.entries(OtpParts));
+    resolvedBase = otpExports.OTPField ?? otpExports.OTPFieldPreview;
+  }
+  return resolvedBase;
+}
+var defaultSlotLabel = (index, length) => `Character ${index + 1} of ${length}`;
+function OtpField({
+  className,
+  length = 6,
+  groupSize,
+  getSlotLabel = defaultSlotLabel,
+  "aria-invalid": ariaInvalid,
+  ...root
+}) {
+  const invalid = ariaInvalid === true || ariaInvalid === "true";
+  const Base = otpBase();
+  return /* @__PURE__ */ jsx(
+    Base.Root,
+    {
+      length,
+      "data-invalid": invalid ? "" : void 0,
+      className: cn("inline-flex max-w-full items-center gap-2", className),
+      ...root,
+      children: Array.from({ length }, (_, index) => (
+        // Slots are positional and never reorder, so the index is the identity.
+        // biome-ignore lint/suspicious/noArrayIndexKey: positional slots
+        /* @__PURE__ */ jsxs(Fragment, { children: [
+          groupSize && index > 0 && index % groupSize === 0 ? /* @__PURE__ */ jsx(
+            "span",
+            {
+              "aria-hidden": "true",
+              "data-otp-gap": "",
+              className: "h-px w-2 shrink-0 bg-border-strong"
+            }
+          ) : null,
+          /* @__PURE__ */ jsx(
+            Base.Input,
+            {
+              "aria-label": index === 0 ? void 0 : getSlotLabel(index, length),
+              "aria-invalid": invalid || void 0,
+              className: cn(
+                "h-(--control-lg) w-(--control-md) min-w-0 text-center text-mono-lg text-foreground caret-primary",
+                // The shell Input wears — lib/field-shell — so a slot reads as
+                // the same field; only the slot-specific states are added here.
+                FIELD_SHELL,
+                // Focus is FIELD_SHELL's ring alone, like every other field — a ring-
+                // coloured border under it made a 3px edge only here.
+                "data-[filled]:border-border-strong",
+                FIELD_INVALID
+              )
+            }
+          )
+        ] }, index)
+      ))
+    }
+  );
+}
+OtpField.displayName = "OtpField";
+export {
+  OtpField
+};

package/dist/components/otp-field/otp-field.meta.js

@@ -0,0 +1,197 @@
+// src/components/otp-field/otp-field.meta.ts
+var otpFieldMeta = {
+  name: "OtpField",
+  summary: "One-time-code entry over Base UI's OTP Field \u2014 one slot per character, SMS autofill on the first slot, paste fills every slot, and only one tab stop for the whole code.",
+  status: "stable",
+  keywords: [
+    "otp",
+    "one-time code",
+    "one-time password",
+    "verification code",
+    "2fa",
+    "two-factor",
+    "mfa",
+    "pin",
+    "passcode",
+    "input otp"
+  ],
+  usage: {
+    description: "Use OtpField for a short, fixed-length code the user copies from somewhere else \u2014 an SMS or email verification code, an authenticator app, a device pairing PIN. The slots show how long the code is and where the user is in it, which a plain Input cannot.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Set `length` to the exact length the server sends, and verify in `onValueComplete` (or with `autoSubmit` inside a form). Most users paste or autofill the whole code at once, so the moment of completion is the natural submit."
+      },
+      {
+        guidance: "do",
+        description: 'Label it through a `Field` ("Verification code") and say where the code was sent in the description. The first slot takes the field\'s name; the rest are announced by position.'
+      },
+      {
+        guidance: "do",
+        description: "Use `groupSize` for codes of 6 or more so the user can check the code in chunks against the message they are reading from."
+      },
+      {
+        guidance: "dont",
+        description: 'Do not use OtpField for a password, an arbitrary-length PIN, or anything the user types from memory. Slots promise a fixed length; use Input with `type="password"` and `autocomplete="current-password"` instead.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not intercept paste or clear the field on a wrong code before the user has seen the error. Blocking paste breaks SMS autofill and password managers, and wiping the slots erases the evidence of which digit was wrong."
+      },
+      {
+        guidance: "dont",
+        description: "Do not swap it for NumberField because the code is digits. A code is an identifier, not a quantity: NumberField strips leading zeros and offers steppers that make no sense here."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Root",
+        required: true,
+        description: "A role=group that holds the value, carries the field label and description, and reports completion."
+      },
+      {
+        name: "Slot",
+        required: true,
+        description: 'One input per character. The first carries autocomplete="one-time-code" and accepts the whole code.'
+      },
+      {
+        name: "Group gap",
+        required: false,
+        description: "A decorative dash inserted every `groupSize` slots; hidden from assistive tech."
+      }
+    ]
+  },
+  related: {
+    components: ["Input", "Form", "NumberField"]
+  },
+  props: [
+    {
+      name: "length",
+      type: "number",
+      default: "6",
+      description: "Number of character slots. Completion fires when every slot is filled."
+    },
+    {
+      name: "groupSize",
+      type: "number",
+      description: "Insert a visual gap every N slots (3 renders 123 \u2013 456). The value stays one contiguous string."
+    },
+    {
+      name: "value / defaultValue",
+      type: "string",
+      description: "Controlled / uncontrolled code."
+    },
+    {
+      name: "onValueChange",
+      type: "(value: string, details) => void",
+      description: "Fires on every edit. `details.reason` is input-change, input-clear, input-paste or keyboard."
+    },
+    {
+      name: "onValueComplete",
+      type: "(value: string, details) => void",
+      description: "Fires once every slot is filled \u2014 the place to verify the code. Also fires when a complete code is pasted over a complete value."
+    },
+    {
+      name: "onValueInvalid",
+      type: "(attempted: string, details) => void",
+      description: "Fires when typed or pasted text contains characters `validationType` rejects, so you can explain the rejection rather than letting it vanish."
+    },
+    {
+      name: "validationType",
+      type: '"numeric" | "alpha" | "alphanumeric" | "none"',
+      default: '"numeric"',
+      description: "Which characters a slot accepts. Also picks the virtual keyboard (numeric \u2192 number pad)."
+    },
+    {
+      name: "autoSubmit",
+      type: "boolean",
+      default: "false",
+      description: "Submit the owning form when the code becomes complete."
+    },
+    {
+      name: "mask",
+      type: "boolean",
+      default: "false",
+      description: "Render slots as password inputs. Only for codes that are secret on screen, such as a card PIN."
+    },
+    {
+      name: "getSlotLabel",
+      type: "(index: number, length: number) => string",
+      default: "Character N of L",
+      description: "Accessible name for slots after the first. Override to localize."
+    },
+    {
+      name: "aria-invalid",
+      type: "boolean",
+      description: "Marks every slot invalid (destructive border). `<Field error>` sets it for you."
+    },
+    {
+      name: "disabled / readOnly / required / name / id / form",
+      type: "\u2014",
+      description: "Standard form-control props. `id` lands on the first slot, so `<Field>` and `<label htmlFor>` name the field."
+    }
+  ],
+  tokensUsed: [
+    "input",
+    "card",
+    "foreground",
+    "muted-foreground",
+    "border-strong",
+    "primary",
+    "ring",
+    "destructive"
+  ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "A code field is part of the form it sits in and appears with it. Animating it in would delay the one thing the user arrived to do \u2014 paste the code they just copied."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Slot",
+      why: "Focus moves between slots on every keystroke. The eased ring and border are what let the eye follow the cursor across six identical boxes instead of hunting for it after each digit."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Slot",
+      why: "A filled slot strengthens its border, so a pasted code visibly lands in every slot at once. Easing it reads as the code arriving rather than the field flickering."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Verifying the code is the form's work, not the field's. Show it on the submit Button's `loading` state, where the user expects the answer to appear."
+    }
+  ],
+  a11y: [
+    'The root is a role=group named by the field label; the first slot shares the label through `id`/`htmlFor`, and later slots are announced by position ("Character 2 of 6").',
+    "Only one slot is in the tab order. Arrow keys, Home/End and Backspace move between slots; Tab leaves the whole field.",
+    'The first slot carries autocomplete="one-time-code" and the numeric virtual keyboard, so iOS and Android offer the SMS code above the keyboard.',
+    "Slots render at 20px (`text-mono-lg`), above the 16px floor that stops iOS Safari zooming on focus."
+  ],
+  examples: [
+    {
+      label: "Six digits",
+      code: '<Field label="Verification code"><OtpField length={6} onValueComplete={verify} /></Field>'
+    },
+    {
+      label: "In a field, grouped",
+      code: '<Field label="Verification code" description="Enter the 6-digit code we sent to your phone."><OtpField length={6} groupSize={3} /></Field>'
+    },
+    {
+      label: "With an error",
+      code: '<Field label="Verification code" error="That code has expired. Request a new code and try again."><OtpField length={6} groupSize={3} defaultValue="482913" /></Field>'
+    },
+    {
+      label: "Alphanumeric",
+      code: '<Field label="Pairing code"><OtpField length={8} groupSize={4} validationType="alphanumeric" /></Field>'
+    }
+  ]
+};
+export {
+  otpFieldMeta
+};

package/dist/components/overflow-menu/index.js

@@ -0,0 +1,7 @@
+// src/components/overflow-menu/index.ts
+import { OverflowMenu } from "./overflow-menu.js";
+import { overflowMenuMeta } from "./overflow-menu.meta.js";
+export {
+  OverflowMenu,
+  overflowMenuMeta
+};

package/dist/components/overflow-menu/overflow-menu.js

@@ -0,0 +1,26 @@
+// src/components/overflow-menu/overflow-menu.tsx
+import { Icon } from "../../icon/index.js";
+import { Button } from "../button/index.js";
+import { Menu, MenuContent, MenuTrigger } from "../menu/index.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function OverflowMenu({
+  children,
+  align = "end",
+  label = "More actions",
+  icon = "ellipsis",
+  size = "icon"
+}) {
+  return /* @__PURE__ */ jsxs(Menu, { children: [
+    /* @__PURE__ */ jsx(
+      MenuTrigger,
+      {
+        render: /* @__PURE__ */ jsx(Button, { variant: "ghost", size, "aria-label": label, children: /* @__PURE__ */ jsx(Icon, { name: icon, variant: "solid" }) })
+      }
+    ),
+    /* @__PURE__ */ jsx(MenuContent, { align, children })
+  ] });
+}
+OverflowMenu.displayName = "OverflowMenu";
+export {
+  OverflowMenu
+};