@sableui/react 0.6.2 → 0.7.1

package/dist/components/chat-composer/chat-composer.js

@@ -0,0 +1,174 @@
+"use client";
+
+// src/components/chat-composer/chat-composer.tsx
+import { useCallback, useRef, useState } from "react";
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { useTypeTier } from "../../lib/density.js";
+import { setRef } from "../../lib/refs.js";
+import { Button } from "../button/index.js";
+import { Textarea } from "../textarea/index.js";
+import { chatComposerVariants } from "./chat-composer.variants.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function ChatComposer({
+  value,
+  defaultValue = "",
+  onValueChange,
+  onSend,
+  placeholder = "Send a message\u2026",
+  busy = false,
+  onStop,
+  disabled = false,
+  invalid = false,
+  attachments,
+  leading,
+  actions,
+  onAttach,
+  label = "Message",
+  sendLabel = "Send message",
+  stopLabel = "Stop generating",
+  footer,
+  fieldRef,
+  className,
+  children,
+  ...props
+}) {
+  const tier = useTypeTier();
+  const [internal, setInternal] = useState(defaultValue);
+  const isControlled = value !== void 0;
+  const text = isControlled ? value : internal;
+  const field = useRef(null);
+  const setField = useCallback(
+    (node) => {
+      setRef(fieldRef, node);
+      field.current = node;
+    },
+    [fieldRef]
+  );
+  const setText = useCallback(
+    (next) => {
+      if (!isControlled) setInternal(next);
+      onValueChange?.(next);
+    },
+    [isControlled, onValueChange]
+  );
+  const canSend = text.trim().length > 0 && !busy && !disabled;
+  const send = useCallback(() => {
+    if (!canSend) return;
+    onSend?.(text.trim());
+    if (!isControlled) setInternal("");
+  }, [canSend, isControlled, onSend, text]);
+  const handleSubmit = useCallback(
+    (event) => {
+      event.preventDefault();
+      send();
+    },
+    [send]
+  );
+  const handleKeyDown = useCallback(
+    (event) => {
+      if (event.key !== "Enter") return;
+      if (event.nativeEvent.isComposing) return;
+      if (event.shiftKey) return;
+      event.preventDefault();
+      send();
+    },
+    [send]
+  );
+  const showStop = busy && Boolean(onStop);
+  return /* @__PURE__ */ jsxs(
+    "form",
+    {
+      onSubmit: handleSubmit,
+      className: cn(chatComposerVariants({ invalid }), className),
+      ...props,
+      children: [
+        attachments ? (
+          // The chips sit p-2 and a 1px border inside this box's corner, so
+          // they take its radius less both (never under 4px) — concentric,
+          // rather than their own rounded-md bulging against the curve.
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              "data-slot": "chat-composer-attachments",
+              className: "flex flex-wrap items-start gap-2 [--attachment-radius:max(--spacing(1),calc(var(--chat-composer-r)-(--spacing(2))-1px))]",
+              children: attachments
+            }
+          )
+        ) : null,
+        /* @__PURE__ */ jsx(
+          Textarea,
+          {
+            ref: setField,
+            autoResize: true,
+            rows: 1,
+            "aria-label": label,
+            "aria-invalid": invalid || void 0,
+            disabled,
+            placeholder,
+            value: text,
+            onChange: (event) => setText(event.target.value),
+            onKeyDown: handleKeyDown,
+            className: cn(
+              // Inline padding puts the text on the attach glyph's edge: an
+              // icon-sm button centres a 1.125rem glyph in --control-sm.
+              "min-h-0 max-h-40 resize-none border-0 bg-transparent px-[calc((var(--control-sm)-1.125rem)/2)] py-1 focus-visible:ring-0",
+              // What you type has to match what it becomes: the field and the
+              // Bubble it turns into both read `prose`, so the message does not
+              // change size the moment it is sent.
+              tier.prose
+            )
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+          onAttach ? /* @__PURE__ */ jsx(
+            Button,
+            {
+              type: "button",
+              variant: "ghost",
+              size: "icon-sm",
+              "aria-label": "Add attachment",
+              disabled,
+              onClick: onAttach,
+              children: /* @__PURE__ */ jsx(Icon, { name: "plus" })
+            }
+          ) : null,
+          leading,
+          /* @__PURE__ */ jsx("div", { className: "flex-1" }),
+          actions,
+          showStop ? /* @__PURE__ */ jsx(
+            Button,
+            {
+              type: "button",
+              variant: "secondary",
+              size: "icon-sm",
+              "aria-label": stopLabel,
+              onClick: onStop,
+              children: /* @__PURE__ */ jsx(Icon, { name: "stop", variant: "solid", className: "text-[0.75em]" })
+            }
+          ) : (
+            // Busy without a stop handler: Button's own `loading` swaps the glyph
+            // for its Spinner and keeps full colour, rather than a hand-spun icon.
+            /* @__PURE__ */ jsx(
+              Button,
+              {
+                type: "submit",
+                size: "icon-sm",
+                "aria-label": sendLabel,
+                disabled: !canSend,
+                loading: busy,
+                children: /* @__PURE__ */ jsx(Icon, { name: "arrow-up" })
+              }
+            )
+          )
+        ] }),
+        footer ? /* @__PURE__ */ jsx("p", { className: cn("px-[calc((var(--control-sm)-1.125rem)/2)] text-muted-foreground", tier.secondary), children: footer }) : null,
+        children
+      ]
+    }
+  );
+}
+ChatComposer.displayName = "ChatComposer";
+export {
+  ChatComposer
+};

package/dist/components/chat-composer/chat-composer.meta.js

@@ -0,0 +1,241 @@
+// src/components/chat-composer/chat-composer.meta.ts
+var chatComposerMeta = {
+  name: "ChatComposer",
+  summary: "The input half of a conversation: one surface holding attachments, an auto-growing field, and its controls. Enter sends, Shift+Enter breaks the line, and send becomes stop while a reply streams.",
+  status: "stable",
+  keywords: [
+    "chat input",
+    "composer",
+    "message input",
+    "prompt input",
+    "send message",
+    "ai chat",
+    "support chat",
+    "textarea"
+  ],
+  usage: {
+    description: "Pairs with MessageScroller to make a working chat. A single surface rather than an input with buttons parked beside it: attachments above, text in the middle, affordances along the bottom. Works controlled or uncontrolled \u2014 uncontrolled is the default because it is what the common case wants, and what lets a hook-free page shell ship a composer that actually types.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Pass `busy` while a reply streams, and `onStop` alongside it. Interrupting a long generation is the most common thing a reader wants during one, and the control belongs where their cursor already is."
+      },
+      {
+        guidance: "do",
+        description: "Leave it uncontrolled unless you need the text elsewhere \u2014 a slash-command menu, a draft you persist. Uncontrolled clears itself on send; controlled does not."
+      },
+      {
+        guidance: "do",
+        description: "Render pending uploads as `<Attachment>` chips in `attachments`, so the file and the message it belongs to stay in one box."
+      },
+      {
+        guidance: "do",
+        description: "Put model pickers and tool toggles in `leading`, beside the attach button \u2014 they are composer state, not message content, and belong on the chrome row rather than in the field."
+      },
+      {
+        guidance: "dont",
+        description: "Do not clear a controlled composer for the user on send. Only the caller knows whether the send succeeded, and clearing on their behalf loses the message when it did not."
+      },
+      {
+        guidance: "dont",
+        description: "Do not add your own Enter-to-send handler on top. The built-in one already guards against firing mid-IME-composition, which is the line hand-rolled chat inputs miss."
+      },
+      {
+        guidance: "do",
+        description: 'Building a docked agent panel inside a tool? Wrap the whole conversation \u2014 scroller, messages and composer \u2014 in `<Density value="compact">`. The entire set follows the workspace register from there: prose drops a tier, the rhythm tightens, and the controls come off the compact ladder. Do not hand-size it at the call site.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it as a general multi-line input. That is `Textarea` \u2014 this one submits on Enter, which is wrong for any field inside a larger form."
+      },
+      {
+        guidance: "dont",
+        description: "Do not override the field's type utility to make it match your transcript. The field and `Bubble` both read the same tier already, which is what stops a message changing size the moment it is sent \u2014 overriding one breaks that pairing."
+      },
+      {
+        guidance: "dont",
+        description: "Do not remove the height cap to let the field grow without limit. A pasted essay would push the conversation off the screen; past the cap it scrolls."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Attachments",
+        required: false,
+        description: "Pending files as chips, above the field, inside the same surface."
+      },
+      {
+        name: "Field",
+        required: true,
+        description: "An auto-growing Textarea, stripped of its own border and ring \u2014 the surface carries both \u2014 capped before it eats the transcript."
+      },
+      {
+        name: "Controls",
+        required: true,
+        description: "Attach and any `leading` controls on the left; `actions` and the send/stop button on the right."
+      },
+      {
+        name: "Footer",
+        required: false,
+        description: "Helper text or a character counter below the controls."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "MessageScroller",
+      "Message",
+      "Bubble",
+      "Attachment",
+      "Textarea"
+    ],
+    patterns: ["ChatPanel"]
+  },
+  props: [
+    {
+      name: "value",
+      type: "string",
+      description: "Controlled value. Omit for an uncontrolled composer that owns its own text."
+    },
+    {
+      name: "defaultValue",
+      type: "string",
+      default: '""',
+      description: "Initial value when uncontrolled."
+    },
+    {
+      name: "onValueChange",
+      type: "(value: string) => void",
+      description: "Notified on every keystroke. Required when `value` is supplied."
+    },
+    {
+      name: "onSend",
+      type: "(value: string) => void",
+      description: "Called with the trimmed message. An uncontrolled composer clears itself afterwards; a controlled one is the caller's to clear."
+    },
+    {
+      name: "placeholder",
+      type: "string",
+      default: '"Send a message\u2026"',
+      description: "Placeholder for the field."
+    },
+    {
+      name: "busy",
+      type: "boolean",
+      default: "false",
+      description: "A reply is streaming. Disables send, and swaps it for a stop control when `onStop` is supplied."
+    },
+    {
+      name: "onStop",
+      type: "() => void",
+      description: "Interrupt the in-flight reply. Supplying it turns send into stop while busy."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      default: "false",
+      description: "Block sending entirely \u2014 over a limit, disconnected, read-only thread. Distinct from `busy`, which is temporary and offers a way out (stop)."
+    },
+    {
+      name: "invalid",
+      type: "boolean",
+      default: "false",
+      description: "Mark the current text invalid. Colours the surface border and sets `aria-invalid` on the field."
+    },
+    {
+      name: "attachments",
+      type: "ReactNode",
+      description: "Attachment chips, shown above the field."
+    },
+    {
+      name: "leading",
+      type: "ReactNode",
+      description: "Controls on the left of the footer row \u2014 model picker, tool toggles."
+    },
+    {
+      name: "actions",
+      type: "ReactNode",
+      description: "Extra controls left of the send button."
+    },
+    {
+      name: "onAttach",
+      type: "() => void",
+      description: "Attach handler. Supplying it renders the built-in attach button."
+    },
+    {
+      name: "label",
+      type: "string",
+      default: '"Message"',
+      description: "Accessible label for the field."
+    },
+    {
+      name: "sendLabel",
+      type: "string",
+      default: '"Send message"',
+      description: "Accessible label for the send button."
+    },
+    {
+      name: "stopLabel",
+      type: "string",
+      default: '"Stop generating"',
+      description: "Accessible label for the stop button."
+    },
+    {
+      name: "footer",
+      type: "ReactNode",
+      description: "Helper text or counter below the controls."
+    },
+    {
+      name: "fieldRef",
+      type: "Ref<HTMLTextAreaElement>",
+      description: "Ref to the underlying textarea \u2014 for focusing after a send, or on mount."
+    },
+    {
+      name: "...form props",
+      type: 'Omit<ComponentPropsWithRef<"form">, "onSubmit" | "defaultValue">',
+      description: "Spread onto the form element. Use `onSend` rather than `onSubmit`."
+    }
+  ],
+  variants: { invalid: ["true", "false"] },
+  tokensUsed: [
+    "card",
+    "input",
+    "ring",
+    "destructive",
+    "foreground",
+    "muted-foreground",
+    "primary",
+    "primary-foreground",
+    "secondary",
+    "secondary-foreground",
+    "accent",
+    "accent-foreground"
+  ],
+  a11y: [
+    "A real `<form>`, so the send button is a submit button and the whole thing behaves as one control to assistive tech and to password managers alike.",
+    "Enter never submits while an IME composition is open (`isComposing`), so a CJK reader confirming a candidate word does not mail a fragment of their first sentence.",
+    "The focus ring is drawn on the surface via `focus-within`, not on the textarea, so the visible focus indicator matches the box a sighted user perceives as the input.",
+    "Send is disabled \u2014 not merely styled down \u2014 until there is non-whitespace to send, so the affordance and the behaviour agree for keyboard users.",
+    "Icon-only attach, send and stop buttons all carry accessible labels, each overridable for localisation."
+  ],
+  examples: [
+    {
+      label: "Uncontrolled \u2014 the common case",
+      code: "<ChatComposer onSend={(text) => send(text)} onAttach={pickFile} />"
+    },
+    {
+      label: "Streaming, with a stop control",
+      code: '<ChatComposer onSend={send} busy={isStreaming} onStop={stop} placeholder="Ask a follow-up\u2026" />'
+    },
+    {
+      label: "Controlled, with pending attachments",
+      code: '<ChatComposer\n	value={draft}\n	onValueChange={setDraft}\n	onSend={(text) => { post(text, files); setDraft("") }}\n	onAttach={pickFile}\n	attachments={files.map((f) => (<Attachment key={f.id} variant="media" name={f.name} thumbnail={f.url} actions={<Button variant="floating" size="icon-xs" aria-label="Remove" onClick={() => drop(f.id)}><Icon name="xmark" /></Button>} />))}\n	footer={`${draft.length} / 4000`}\n	invalid={draft.length > 4000}\n/>'
+    },
+    {
+      label: "A working chat, end to end",
+      code: '<div className="flex h-128 flex-col gap-3">\n	<MessageScroller className="flex-1 min-h-0">\n		{messages.map((m) => (<Message key={m.id} messageId={m.id} align={m.mine ? "end" : "start"}><Bubble variant={m.mine ? "primary" : "muted"} align={m.mine ? "end" : "start"}>{m.body}</Bubble></Message>))}\n		{streaming ? <Marker icon="spinner" spin shimmer>Thinking\u2026</Marker> : null}\n	</MessageScroller>\n	<ChatComposer onSend={send} busy={streaming} onStop={stop} />\n</div>'
+    }
+  ]
+};
+export {
+  chatComposerMeta
+};

package/dist/components/chat-composer/chat-composer.variants.js

@@ -0,0 +1,17 @@
+// src/components/chat-composer/chat-composer.variants.ts
+import { cva } from "class-variance-authority";
+var chatComposerVariants = cva(
+  "flex w-full flex-col gap-2 border border-input bg-card p-2 motion-interactive focus-within:ring-2 focus-within:ring-ring [--chat-composer-r:var(--chat-composer-radius,var(--card-inner-radius,calc(min(var(--button-radius,9999px),var(--control-sm)/2)+(--spacing(2))+1px)))] rounded-[var(--chat-composer-r)]",
+  {
+    variants: {
+      invalid: {
+        true: "border-destructive",
+        false: ""
+      }
+    },
+    defaultVariants: { invalid: false }
+  }
+);
+export {
+  chatComposerVariants
+};

package/dist/components/chat-composer/index.js

@@ -0,0 +1,7 @@
+// src/components/chat-composer/index.ts
+import { ChatComposer } from "./chat-composer.js";
+import { chatComposerMeta } from "./chat-composer.meta.js";
+export {
+  ChatComposer,
+  chatComposerMeta
+};

package/dist/components/checkbox/checkbox-mark.js

@@ -0,0 +1,28 @@
+// src/components/checkbox/checkbox-mark.tsx
+import { Checkbox as Base } from "@base-ui/react/checkbox";
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { CHECK_MARK_SIZE } from "../../lib/selection-card.js";
+import { jsx } from "react/jsx-runtime";
+function CheckboxMark({ className }) {
+  return /* @__PURE__ */ jsx(
+    Base.Indicator,
+    {
+      className: cn(
+        "flex items-center justify-center text-current motion-interactive ease-spring data-[starting-style]:scale-0 data-[starting-style]:opacity-0 data-[ending-style]:scale-0 data-[ending-style]:opacity-0",
+        className
+      ),
+      render: (indicatorProps, state) => /* @__PURE__ */ jsx("span", { ...indicatorProps, children: /* @__PURE__ */ jsx(
+        Icon,
+        {
+          name: state.indeterminate ? "minus" : "check",
+          className: cn(CHECK_MARK_SIZE, "[&_path]:stroke-current [&_path]:[stroke-width:2] [&_path]:[stroke-linejoin:round] [&_path]:[stroke-linecap:round]")
+        }
+      ) })
+    }
+  );
+}
+CheckboxMark.displayName = "CheckboxMark";
+export {
+  CheckboxMark
+};

package/dist/components/checkbox/checkbox.js

@@ -0,0 +1,30 @@
+// src/components/checkbox/checkbox.tsx
+import { Checkbox as Base } from "@base-ui/react/checkbox";
+import { cn } from "../../lib/cn.js";
+import { CHECK_BOX } from "../../lib/selection-card.js";
+import { CheckboxMark } from "./checkbox-mark.js";
+import { jsx } from "react/jsx-runtime";
+function Checkbox({ className, children, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Root,
+    {
+      className: cn(
+        CHECK_BOX,
+        "text-primary-foreground",
+        "data-[checked]:border-primary data-[checked]:bg-primary",
+        "data-[indeterminate]:border-primary data-[indeterminate]:bg-primary",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        // Base UI renders the root as a <span>, which `:disabled` never matches —
+        // the state is the data attribute, as on Switch.
+        "data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50",
+        className
+      ),
+      ...props,
+      children: children ?? /* @__PURE__ */ jsx(CheckboxMark, {})
+    }
+  );
+}
+Checkbox.displayName = "Checkbox";
+export {
+  Checkbox
+};

package/dist/components/checkbox/checkbox.meta.js

@@ -0,0 +1,127 @@
+// src/components/checkbox/checkbox.meta.ts
+var checkboxMeta = {
+  name: "Checkbox",
+  summary: "Square toggle (18px at rest, on the spacing scale) over Base UI's Checkbox. Checked/indeterminate/disabled states; controlled or uncontrolled; form-ready via the hidden native input.",
+  status: "stable",
+  keywords: [
+    "checkbox",
+    "boolean",
+    "multi select",
+    "form control"
+  ],
+  usage: {
+    description: "Use Checkbox for independent boolean choices or for selecting multiple options in a set.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use Checkbox when each option can be toggled independently."
+      },
+      {
+        guidance: "do",
+        description: "Attach a visible label that explains the consequence of checking the control."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Checkbox for mutually exclusive choices; use Radio or Select instead."
+      },
+      {
+        guidance: "dont",
+        description: 'Do not use it without a label or an aria-label. An 18px square with no accessible name is announced as just "checkbox", which tells a screen-reader user nothing about what they are agreeing to.'
+      },
+      {
+        guidance: "dont",
+        description: `Do not phrase the label as a negative, such as "Don't send read receipts". Paired with an unchecked box it becomes a double negative the reader has to solve before they can answer. Label the state being turned on.`
+      }
+    ]
+  },
+  related: {
+    components: [
+      "CheckboxCard",
+      "Switch",
+      "Radio"
+    ]
+  },
+  props: [
+    {
+      name: "checked",
+      type: "boolean",
+      description: "Controlled checked state. Pair with onCheckedChange. Omit for uncontrolled."
+    },
+    {
+      name: "defaultChecked",
+      type: "boolean",
+      default: "false",
+      description: "Initial checked state for an uncontrolled checkbox."
+    },
+    {
+      name: "onCheckedChange",
+      type: "(checked: boolean, eventDetails) => void",
+      description: "Fires when the checkbox is ticked or unticked. Note: Base UI passes a second eventDetails arg \u2014 not the common (checked) => void, so a single-arg handler must widen its signature."
+    },
+    {
+      name: "indeterminate",
+      type: "boolean",
+      default: "false",
+      description: 'Mixed state (neither checked nor unchecked). Renders a dash instead of the check. For a "select all" box inside a CheckboxGroup, use `parent` instead and the group sets this for you.'
+    },
+    {
+      name: "parent",
+      type: "boolean",
+      default: "false",
+      description: 'Makes this the "select all" box of a CheckboxGroup that has `allValues`. It checks or clears every child, and shows the dash when only some are checked. Only works inside a CheckboxGroup.'
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      default: "false",
+      description: "Ignores user interaction and dims the control."
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Field name for the hidden input on form submit."
+    },
+    {
+      name: "value",
+      type: "string",
+      description: "Value submitted with the form when checked. Inside a group-owned CheckboxGroup, it is the name the group's value array uses for this checkbox."
+    },
+    {
+      name: "render",
+      type: "ReactElement | (props, state) => ReactElement",
+      description: "Compose the root with another element through the Base UI render prop."
+    }
+  ],
+  tokensUsed: [
+    "card",
+    "input",
+    "primary",
+    "primary-foreground",
+    "ring"
+  ],
+  a11y: [
+    "Base UI renders a hidden native <input type=checkbox> for keyboard, focus, and form semantics.",
+    "Space toggles; focus-visible draws a 2px ring in the --ring token.",
+    "indeterminate sets aria-checked=mixed automatically; a `parent` checkbox in a CheckboxGroup gets aria-checked=mixed and aria-controls for its children from the group.",
+    `Label it with Field orientation="horizontal": it wires the label's htmlFor to the checkbox, so the label text joins the click target, and adds the description and error plumbing.`
+  ],
+  examples: [
+    { label: "Default", code: "<Checkbox defaultChecked />" },
+    {
+      label: "Controlled",
+      code: "<Checkbox checked={value} onCheckedChange={setValue} />"
+    },
+    { label: "Indeterminate", code: "<Checkbox indeterminate />" },
+    {
+      label: "Select all in a group",
+      code: '<CheckboxGroup allValues={["email", "sms"]} defaultValue={["email"]} className="gap-3"><Field label="All channels" orientation="horizontal"><Checkbox parent /></Field><Field label="Email" orientation="horizontal" className="ps-7"><Checkbox value="email" /></Field><Field label="SMS" orientation="horizontal" className="ps-7"><Checkbox value="sms" /></Field></CheckboxGroup>'
+    },
+    {
+      label: "With label",
+      code: '<Field label="Remember me" orientation="horizontal"><Checkbox /></Field>'
+    }
+  ]
+};
+export {
+  checkboxMeta
+};

package/dist/components/checkbox/index.js

@@ -0,0 +1,7 @@
+// src/components/checkbox/index.ts
+import { Checkbox } from "./checkbox.js";
+import { checkboxMeta } from "./checkbox.meta.js";
+export {
+  Checkbox,
+  checkboxMeta
+};