@sableui/react 0.6.2 → 0.7.1

package/dist/components/calendar/calendar.meta.js

@@ -0,0 +1,136 @@
+// src/components/calendar/calendar.meta.ts
+var calendarMeta = {
+  name: "Calendar",
+  summary: "Date picker grid wrapping react-day-picker v9, themed entirely with semantic tokens (no external stylesheet). Supports single, multiple, and range selection; nav chevrons render through the injected icon set.",
+  status: "stable",
+  keywords: [
+    "calendar",
+    "date grid",
+    "month",
+    "schedule"
+  ],
+  usage: {
+    description: "Use Calendar to browse or choose dates in a month grid, especially when relative date position matters.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it when users need to compare weekdays, ranges, or nearby dates."
+      },
+      {
+        guidance: "do",
+        description: "Provide selected, disabled, and today states when date choice is interactive."
+      },
+      {
+        guidance: "dont",
+        description: 'Do not use Calendar when a compact DatePicker (with granularity="minute" for a time) would be faster.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it as the only way to enter a date. A grid is slow for a date far from today and unusable for someone who knows the value \u2014 always pair it with a text input."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "DatePicker"
+    ]
+  },
+  props: [
+    {
+      name: "mode",
+      type: '"single" | "multiple" | "range"',
+      description: "Selection behavior. Pair with the matching selected/onSelect shape (Date, Date[], or DateRange)."
+    },
+    {
+      name: "selected",
+      type: "Date | Date[] | DateRange | undefined",
+      description: "The controlled selection. Shape follows mode."
+    },
+    {
+      name: "onSelect",
+      type: "(value, triggerDate, modifiers, event) => void",
+      description: "Fires when a day is chosen. The first argument's type follows mode."
+    },
+    {
+      name: "defaultMonth",
+      type: "Date",
+      description: "The month shown on first render (uncontrolled navigation)."
+    },
+    {
+      name: "month",
+      type: "Date",
+      description: "Controlled displayed month; pair with onMonthChange."
+    },
+    {
+      name: "numberOfMonths",
+      type: "number",
+      default: "1",
+      description: "How many month grids to render side by side."
+    },
+    {
+      name: "disabled",
+      type: "Matcher | Matcher[]",
+      description: "Days matching this are dimmed and non-selectable (e.g. { before: new Date() })."
+    },
+    {
+      name: "showOutsideDays",
+      type: "boolean",
+      default: "true",
+      description: "Render leading/trailing days from adjacent months, dimmed."
+    },
+    {
+      name: "bare",
+      type: "boolean",
+      default: "false",
+      description: "Drop the card frame (border, fill, padding) so the grid sits flush inside a surface that already has one, such as a Popover. DatePicker renders its Calendar this way."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Merged onto the bordered card container that wraps the grid."
+    },
+    {
+      name: "classNames",
+      type: "Partial<ClassNames>",
+      description: "Per-part class overrides merged over the themed defaults. Themed slots: months, month, nav, button_previous, button_next, month_caption, caption_label, month_grid, weekdays, weekday, week, day, day_button, range_start, range_middle, range_end, selected, today, outside, disabled, hidden. Selection/state slots (selected/today/range_*/outside/disabled) style the day CELL; the inner day button is targeted via the [&>button] descendant."
+    },
+    {
+      name: "components",
+      type: "Partial<CustomComponents>",
+      description: "Render overrides for RDP parts. Chevron is supplied by default and merged with yours."
+    }
+  ],
+  variants: {
+    mode: ["single", "multiple", "range"]
+  },
+  tokensUsed: [
+    "card",
+    "card-foreground",
+    "border",
+    "primary",
+    "primary-foreground",
+    "accent",
+    "accent-foreground",
+    "muted-foreground",
+    "ring"
+  ],
+  a11y: [
+    "react-day-picker manages the roving-tabindex grid, arrow-key navigation, and ARIA roles/labels for the calendar.",
+    "Selected days use bg-primary/text-primary-foreground for AA contrast; today is marked with a dot under the number (not a ring, which is reserved for keyboard focus) rather than color alone.",
+    "Disabled and outside days are dimmed and removed from the tab order.",
+    "Nav chevrons resolve through the injected IconProvider; ensure chevron-left and chevron-right are registered in the icon set."
+  ],
+  examples: [
+    {
+      label: "Single date",
+      code: 'const [date, setDate] = useState<Date>()\n<Calendar mode="single" selected={date} onSelect={setDate} />'
+    },
+    {
+      label: "Range",
+      code: 'const [range, setRange] = useState<DateRange>()\n<Calendar mode="range" selected={range} onSelect={setRange} numberOfMonths={2} />'
+    }
+  ]
+};
+export {
+  calendarMeta
+};

package/dist/components/calendar/index.js

@@ -0,0 +1,7 @@
+// src/components/calendar/index.ts
+import { Calendar } from "./calendar.js";
+import { calendarMeta } from "./calendar.meta.js";
+export {
+  Calendar,
+  calendarMeta
+};

package/dist/components/card/card.js

@@ -0,0 +1,203 @@
+// src/components/card/card.tsx
+import { useContext } from "react";
+import { useRender } from "@base-ui/react/use-render";
+import { BLEED_LAST_END } from "../../lib/bleed.js";
+import { cn } from "../../lib/cn.js";
+import { CardDepthContext, StackedActionsContext, usePresentation } from "../../lib/presentation.js";
+import { jsx } from "react/jsx-runtime";
+var DENSITY_PAD = {
+  comfortable: "calc(var(--spacing) * 6)",
+  // p-6
+  compact: "calc(var(--spacing) * 4)"
+  // p-4
+};
+var INTERACTIVE_BASE = "[&:is(a[href],button)]:motion-interactive [&:is(a[href],button)]:cursor-pointer [&:is(button)]:w-full [&:is(button)]:text-start focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+var INTERACTIVE_HOVER = {
+  default: "[&:is(a[href],button)]:hover:border-border-strong [&:is(a[href],button)]:hover:shadow-md",
+  flat: "[&:is(a[href],button)]:hover:bg-muted"
+};
+function Card({
+  variant = "default",
+  density = "comfortable",
+  className,
+  style,
+  render,
+  ref,
+  ...props
+}) {
+  const depth = useContext(CardDepthContext);
+  const bleed = usePresentation() === "sheet" && variant === "flat" && depth === 0;
+  const element = useRender({
+    render: render ?? /* @__PURE__ */ jsx("div", {}),
+    ref,
+    props: {
+      ...props,
+      className: cn(
+        // group/card: parts can answer the card's hover, e.g. a trailing
+        // chevron with `group-hover/card:translate-x-0.5`.
+        "group/card block rounded-lg text-card-foreground",
+        // The corner a box inset by the card padding should wear: concentric
+        // (card radius less padding and border), floored at radius-sm like
+        // sable-frame — at Sable's paddings the subtraction runs to ~0, and a
+        // near-square box inside a rounded card reads as another system.
+        // A field or panel inside reads it (ChatComposer does).
+        "[--card-inner-radius:max(var(--radius-sm),calc(var(--radius-lg)-var(--card-p)-1px))]",
+        // Declares its surface so sable-well / sable-surface-interactive inside derive from the card.
+        variant === "default" && "border border-border bg-card shadow-sm [--sable-surface-bg:var(--card)]",
+        // A CardList or a flush CardContent (an edge-to-edge Table) runs its
+        // rows to the card's edges, and a row's hover fill or a TableFooter's
+        // tint would otherwise poke square corners out past the card's
+        // rounded ones — clip to the card's own curve instead. Nothing
+        // overflows on purpose here: the table insets its edge cells by
+        // --table-edge-px, so focus rings stay inside, and menus portal out.
+        "has-data-[slot=card-list]:overflow-clip has-[[data-slot=card-content][data-flush]]:overflow-clip",
+        INTERACTIVE_BASE,
+        INTERACTIVE_HOVER[variant],
+        className
+      ),
+      style: {
+        "--card-p": DENSITY_PAD[density],
+        ...bleed ? { margin: "calc(var(--card-p) * -1)", width: "calc(100% + var(--card-p) * 2)", maxWidth: "none" } : null,
+        ...style
+      }
+    },
+    defaultTagName: "div"
+  });
+  return /* @__PURE__ */ jsx(CardDepthContext.Provider, { value: depth + 1, children: element });
+}
+Card.displayName = "Card";
+function CardHeader({
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-slot": "card-header",
+      className: cn(
+        // Grid so an optional CardAction can pin to the top-right. Without
+        // one it collapses to a single stacked column (same as before).
+        // Zeroes its own bottom padding so it owns the CardHeader/CardContent
+        // seam — CardContent always has full padding on its own (see below),
+        // so a standalone CardContent never loses its top padding. As the
+        // card's last child (a stat card: label, number, sparkline) nothing
+        // follows to pad the bottom, so it keeps its own; zeroed, the number
+        // sat on the card's bottom edge.
+        "grid auto-rows-min grid-cols-1 items-start gap-1.5 p-[var(--card-p,--spacing(6))] pb-0 last:pb-[var(--card-p,--spacing(6))] has-data-[slot=card-action]:grid-cols-[1fr_auto]",
+        className
+      ),
+      ...props
+    }
+  );
+}
+function CardAction({
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-slot": "card-action",
+      className: cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        BLEED_LAST_END,
+        className
+      ),
+      ...props
+    }
+  );
+}
+function CardTitle({ className, render, ref, ...props }) {
+  return useRender({
+    render: render ?? /* @__PURE__ */ jsx("div", {}),
+    ref,
+    props: { ...props, className: cn("text-title-lg", className) },
+    defaultTagName: "div"
+  });
+}
+function CardDescription({
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "p",
+    {
+      className: cn("text-body-sm text-muted-foreground", className),
+      ...props
+    }
+  );
+}
+function CardContent({
+  className,
+  flush = false,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-slot": "card-content",
+      "data-flush": flush ? "" : void 0,
+      className: cn(
+        flush ? "p-0 [--table-edge-px:var(--card-p,--spacing(6))]" : "p-[var(--card-p,--spacing(6))]",
+        className
+      ),
+      ...props
+    }
+  );
+}
+function CardList({
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-slot": "card-list",
+      className: cn(
+        "flex flex-col divide-y divide-border [--entity-radius:0px] [--entity-px:var(--card-p,--spacing(6))] [--entity-py:calc(var(--card-p,--spacing(6))/2)]",
+        // Between rows the half padding is enough (each side of a hairline
+        // gets it); against the card's own edge the first and last rows take
+        // the full card padding, so the list is inset like every other card.
+        "*:first:pt-[var(--card-p,--spacing(6))] *:last:pb-[var(--card-p,--spacing(6))]",
+        "[[data-slot=card-header]+&]:mt-[calc(var(--card-p,--spacing(6))/2)] [[data-slot=card-header]+&]:border-t [[data-slot=card-header]+&]:border-border",
+        className
+      ),
+      ...props
+    }
+  );
+}
+function CardFooter({
+  actions = false,
+  className,
+  children,
+  ...props
+}) {
+  const depth = useContext(CardDepthContext);
+  const stacked = usePresentation() === "sheet" && actions && depth <= 1;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-slot": "card-footer",
+      "data-actions": actions ? stacked ? "stack" : "row" : void 0,
+      className: cn(
+        "flex items-center gap-2 p-[var(--card-p,--spacing(6))] pt-0",
+        "[[data-slot=card-header]+&]:pt-[var(--card-p,--spacing(6))]",
+        "[:is([data-slot=card-list],[data-slot=card-content][data-flush])+&]:border-t [:is([data-slot=card-list],[data-slot=card-content][data-flush])+&]:border-border [:is([data-slot=card-list],[data-slot=card-content][data-flush])+&]:pt-[var(--card-p,--spacing(6))]",
+        className,
+        stacked && "mt-auto flex-col-reverse items-stretch justify-start"
+      ),
+      ...props,
+      children: stacked ? /* @__PURE__ */ jsx(StackedActionsContext.Provider, { value: true, children }) : children
+    }
+  );
+}
+export {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardList,
+  CardTitle
+};

package/dist/components/card/card.meta.js

@@ -0,0 +1,212 @@
+// src/components/card/card.meta.ts
+var cardMeta = {
+  name: "Card",
+  summary: "Raised surface container (rounded-lg) with optional Header/Title/Description/Action/Content/Footer parts. A density knob trades the part padding (comfortable vs compact) for denser section panels. `render` makes the whole card one link or button, with a hover, a full-card focus ring and motion.",
+  keywords: [
+    "card",
+    "surface",
+    "panel",
+    "container",
+    "tile",
+    "section",
+    "header",
+    "footer",
+    "settings",
+    "link card",
+    "clickable card",
+    "nav card"
+  ],
+  usage: {
+    description: "Use Card for a discrete thing with its own boundary, such as one product, one notification, one metric, or one setting cluster. Do not use Card as the default way to group every page section; whitespace, headings, Stack, Section, and dividers often create cleaner hierarchy.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use Card when the item could be reordered, removed, selected, or compared independently."
+      },
+      {
+        guidance: "do",
+        description: "Keep sibling cards on the same density and padding rhythm so lists and grids scan cleanly."
+      },
+      {
+        guidance: "do",
+        description: "Use CardHeader, CardContent, and CardFooter when the card has a stable title/body/action structure."
+      },
+      {
+        guidance: "do",
+        description: 'Make the whole card one link (`render={<a href="\u2026" />}`) when the card IS a single destination \u2014 a nav tile, a gallery item, a news teaser \u2014 and nothing inside it is interactive. All of the card text becomes the accessible name of the link, so keep it short: a title and a line.'
+      },
+      {
+        guidance: "dont",
+        description: "Make a card a link when it holds its own buttons, menus, switches or links. Interactive content nested in a link is invalid HTML and announces twice; keep the card a plain surface and put the link on its title or in CardFooter instead."
+      },
+      {
+        guidance: "dont",
+        description: "Wrap every settings section or form group in a card; use headings, Stack, or the SettingsPage pattern instead."
+      },
+      {
+        guidance: "dont",
+        description: "Nest cards inside cards. Flatten the hierarchy or use dividers and spacing inside one card."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Container",
+        required: true,
+        description: "The raised or flat surface that creates the item boundary."
+      },
+      {
+        name: "Header",
+        required: false,
+        description: "Optional title, description, and aligned action area for the card's identity."
+      },
+      {
+        name: "Content",
+        required: true,
+        description: "The body region. It should contain the information or controls that belong to this one item."
+      },
+      {
+        name: "Footer",
+        required: false,
+        description: "Optional action or metadata row, usually lower-emphasis than the header."
+      }
+    ]
+  },
+  related: {
+    components: ["Region", "Stack", "Separator", "Button", "Badge"],
+    patterns: ["DashboardPage", "SettingsPage", "ListDetailPage"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "variant",
+      type: '"default" | "flat"',
+      default: '"default"',
+      description: '"default" raises with bg-card + border + soft shadow; "flat" is transparent.'
+    },
+    {
+      name: "density",
+      type: '"comfortable" | "compact"',
+      default: '"comfortable"',
+      description: "Padding of the Header/Content/Footer parts: comfortable = p-6 (default), compact = p-4 for denser section panels (pair compact with the flat variant for a settings / form section panel). Threaded to the parts via the inherited --card-p custom property. Card sets --card-p via inline style, which beats a plain (non-!important) stylesheet override of the same property on the same element \u2014 use this prop rather than a className override; if an external override is unavoidable, it needs !important."
+    },
+    {
+      name: "render",
+      type: "useRender.RenderProp",
+      description: 'Replace the rendered element through the Base UI render prop \u2014 most often `render={<a href="/x" />}` (or a router Link) to make the whole card one link. When the rendered element is a link (a[href]) or a button, the card gains a hover state (stronger border and shadow; a muted fill when flat), a full-card focus-visible ring and motion-interactive easing. Any other element (article, li) stays a static surface. Children can answer the hover with `group-hover/card:`.'
+    }
+  ],
+  subcomponents: [
+    {
+      name: "CardHeader",
+      type: 'ComponentPropsWithRef<"div">',
+      description: "Top section holding CardTitle/CardDescription (and optionally CardAction). Padding follows the density knob."
+    },
+    {
+      name: "CardTitle",
+      type: 'ComponentPropsWithRef<"div"> & { render?: useRender.RenderProp }',
+      description: "The card's name (text-title-lg). A div by default; pass `render={<h2 />}` (or h3\u2026) to make it a heading in the page outline, at the level the card's position calls for."
+    },
+    {
+      name: "CardDescription",
+      type: 'ComponentPropsWithRef<"div">',
+      description: "Muted supporting line under the title."
+    },
+    {
+      name: "CardAction",
+      type: 'ComponentPropsWithRef<"div">',
+      description: `Header-aligned top-right action slot (e.g. an overflow menu, switch, or close button). Place inside CardHeader, which becomes a 2-column grid when present and collapses to a single column otherwise. A ghost or link Button that ends the slot bleeds by its own padding at the end, so a "View all" label or a "\u22EF" glyph sits on the card's content edge; filled buttons keep their edge there.`
+    },
+    {
+      name: "CardContent",
+      type: 'ComponentPropsWithRef<"div"> & { flush?: boolean }',
+      description: "The body region. Padding follows the density knob on all sides \u2014 does not assume a preceding CardHeader, so it is safe to use standalone (e.g. no CardHeader in the card). When paired with CardHeader, the seam stays tight because CardHeader zeroes its own bottom padding. `flush` runs it edge to edge for a table: the Table insets its first and last columns by exactly the card padding, so it lines up with the header \u2014 never hand-set pl-6/pr-6 on columns."
+    },
+    {
+      name: "CardList",
+      type: 'ComponentPropsWithRef<"div">',
+      description: "Rows that run edge to edge in the card (Entity rows, most often), divided by hairlines. Insets each row to the card's own padding, so a list card lines up with every other card at any density \u2014 no hand-tuned px-* on the rows. Under a CardHeader it opens with a hairline and a gap; alone it fills the card."
+    },
+    {
+      name: "CardFooter",
+      type: 'ComponentPropsWithRef<"div"> & { actions?: boolean }',
+      description: "Bottom row for actions/meta. Padding follows the density knob. `actions` marks it as the card's action row (buttons only): in a sheet (IosSheet, a bottom SheetContent) it becomes a full-width stack pinned to the bottom, primary on top; on a page nothing changes."
+    }
+  ],
+  variants: {
+    variant: ["default", "flat"],
+    density: ["comfortable", "compact"]
+  },
+  tokensUsed: [
+    "card",
+    "card-foreground",
+    "border",
+    "border-strong",
+    "muted",
+    "muted-foreground",
+    "ring"
+  ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Container",
+      why: "A card is part of the layout it ships in; whatever stages that region owns the entrance. A card that fades in on its own delays reading the thing it holds."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Container",
+      why: "Only when the card is rendered as a link or button. The border, shadow and ring ease in so the pointer reads as landing on one target, not as the grid flickering. No motion-press: a 0.97 settle on a surface this large reads as the layout lurching. A static card has no response, so it gets no transition."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Container",
+      why: "A card has no states of its own to move between. Selection is CheckboxCard or RadioCard; disclosure is Collapsible or Accordion."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Container",
+      why: "A card does not work on anything. Loading content inside it is a Skeleton's job."
+    }
+  ],
+  a11y: [
+    "Purely presentational by default; add headings/landmarks in content as needed.",
+    "Rendered as a link or button, the whole card is one target: its full text is the accessible name, and the focus ring wraps the whole card. Nothing interactive may sit inside it \u2014 nested links or buttons inside a link are invalid and unreachable for keyboard users in some browsers.",
+    "A Card is a container, not a landmark and not a heading. If its title is the only heading in the region, render it as a real heading element with a title tier \u2014 a visually-styled div gives screen-reader heading navigation nothing to find."
+  ],
+  examples: [
+    {
+      label: "With parts",
+      code: '<Card><CardHeader><CardTitle>Edition</CardTitle><CardDescription>Limited run of 100.</CardDescription></CardHeader><CardContent><p className="text-body-md">Each collector receives a signed print and the on-chain edition.</p></CardContent></Card>'
+    },
+    {
+      label: "With a header action",
+      code: '<Card><CardHeader><CardTitle>Edition</CardTitle><CardAction><Button variant="ghost" size="icon-sm" aria-label="More"><Icon name="ellipsis" /></Button></CardAction></CardHeader><CardContent><p className="text-body-md text-muted-foreground">24 of 100 collected.</p></CardContent></Card>'
+    },
+    {
+      label: "Compact section panel",
+      code: '<Card variant="flat" density="compact"><CardHeader><CardTitle>Notifications</CardTitle></CardHeader><CardContent><p className="text-body-sm text-muted-foreground">Push and email are enabled.</p></CardContent></Card>'
+    },
+    {
+      label: "Product card with actions",
+      code: '<Card><CardHeader><CardTitle>Midnight Archive</CardTitle><CardDescription>Edition #24 of 100</CardDescription><CardAction><Badge tone="edition">Edition</Badge></CardAction></CardHeader><CardContent><p className="text-body-sm text-muted-foreground">A signed print and token-gated download for collectors.</p></CardContent><CardFooter><Button size="sm">Collect</Button><Button size="sm" variant="ghost">Preview</Button></CardFooter></Card>'
+    },
+    {
+      label: "Whole card as a link",
+      code: '<Card render={<a href="/components" />}><CardContent className="flex items-center justify-between gap-4"><div className="min-w-0"><CardTitle>Components</CardTitle><CardDescription>Every building block, with live examples.</CardDescription></div><Icon name="chevron-right" className="text-sm text-muted-foreground motion-interactive group-hover/card:translate-x-0.5 group-hover/card:text-foreground" /></CardContent></Card>'
+    },
+    {
+      label: "Metric card",
+      code: '<Card density="compact"><CardHeader><CardTitle>Revenue</CardTitle><CardDescription>Last 30 days</CardDescription></CardHeader><CardContent><p className="text-heading-3">128.4 SOL</p><p className="text-body-sm text-success">+12.8% from previous period</p></CardContent></Card>'
+    },
+    {
+      label: "List card",
+      code: "<Card><CardHeader><CardTitle>Members</CardTitle><CardDescription>3 people can edit this space.</CardDescription></CardHeader><CardList>{people.map((p) => <Entity key={p.id} interactive onSelect={() => open(p)} leading={<Avatar fallback={p.initials} alt={p.name} />} title={p.name} subtitle={p.role} />)}</CardList></Card>"
+    }
+  ]
+};
+export {
+  cardMeta
+};

package/dist/components/card/index.js

@@ -0,0 +1,23 @@
+// src/components/card/index.ts
+import {
+  Card,
+  CardHeader,
+  CardAction,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardList,
+  CardFooter
+} from "./card.js";
+import { cardMeta } from "./card.meta.js";
+export {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardList,
+  CardTitle,
+  cardMeta
+};