@gtivr4/a1-design-system-react 0.13.3 → 0.15.0

package/src/components/split-button/SplitButton.jsx

@@ -0,0 +1,92 @@
+import "./split-button.css";
+import { useRef, useState } from "react";
+import { Button } from "../button/Button.jsx";
+import { Menu, MenuItem } from "../menu/Menu.jsx";
+import { Icon } from "../icon/Icon.jsx";
+
+const variants = ["primary", "secondary", "tertiary", "destructive", "success"];
+const sizes = ["sm", "md", "lg"];
+
+/**
+ * SplitButton — a primary action with an attached caret target that opens a Menu
+ * of related/secondary actions. The main button runs the default action; the
+ * toggle (caret) on its inline-end opens the menu. Built from the A1 `Button` and
+ * `Menu`, so styling, keyboard, and focus come from those components.
+ *
+ * `actions` is `{ id, label, icon?, disabled?, onClick? }[]`.
+ */
+export function SplitButton({
+  children,
+  onClick,
+  variant = "primary",
+  size = "md",
+  icon,
+  iconPosition = "start",
+  loading = false,
+  disabled = false,
+  actions = [],
+  menuLabel = "More actions",
+  toggleLabel = "More actions",
+  className = "",
+  ...rest
+}) {
+  const [open, setOpen] = useState(false);
+  const toggleRef = useRef(null);
+
+  const resolvedVariant = variants.includes(variant) ? variant : "primary";
+  const resolvedSize = sizes.includes(size) ? size : "md";
+  const isInert = disabled || loading;
+
+  // The toggle reuses the Button class layer (variant/size design tokens) on a
+  // raw <button> so it can be ref'd as the menu anchor (Button doesn't forward refs).
+  const toggleClasses = [
+    "a1-button",
+    `a1-button--${resolvedVariant}`,
+    resolvedSize !== "md" && `a1-button--${resolvedSize}`,
+    "a1-split-button__toggle",
+  ].filter(Boolean).join(" ");
+
+  return (
+    <div
+      className={["a1-split-button", isInert && "a1-split-button--disabled", className].filter(Boolean).join(" ")}
+      {...rest}
+    >
+      <Button
+        className="a1-split-button__main"
+        variant={resolvedVariant}
+        size={resolvedSize}
+        icon={icon}
+        iconPosition={iconPosition}
+        loading={loading}
+        disabled={disabled}
+        onClick={onClick}
+      >
+        {children}
+      </Button>
+      <button
+        ref={toggleRef}
+        type="button"
+        className={toggleClasses}
+        aria-label={toggleLabel}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        disabled={isInert}
+        onClick={() => setOpen((current) => !current)}
+      >
+        <Icon name="arrow_drop_down" className="a1-split-button__caret" aria-hidden="true" />
+      </button>
+      <Menu open={open} onClose={() => setOpen(false)} anchorRef={toggleRef} aria-label={menuLabel}>
+        {actions.map((action) => (
+          <MenuItem
+            key={action.id}
+            icon={action.icon}
+            disabled={action.disabled}
+            onClick={() => { action.onClick?.(); setOpen(false); }}
+          >
+            {action.label}
+          </MenuItem>
+        ))}
+      </Menu>
+    </div>
+  );
+}

package/src/components/split-button/split-button.css

@@ -0,0 +1,40 @@
+/* ══════════════════════════════════════════════════════════════════════════
+   Split Button — a primary action joined to a caret toggle that opens a Menu.
+   ══════════════════════════════════════════════════════════════════════════ */
+
+.a1-split-button {
+  display: inline-flex;
+  align-items: stretch;
+}
+
+/* The two targets sit flush; the main rounds its inline-start corners, the
+   toggle rounds its inline-end corners, so together they read as one pill. */
+.a1-split-button__main {
+  --a1-button-border-radius: var(--component-button-border-radius) 0 0 var(--component-button-border-radius);
+}
+
+.a1-split-button__toggle {
+  --a1-button-border-radius: 0 var(--component-button-border-radius) var(--component-button-border-radius) 0;
+  /* A snug caret target rather than a full text button's inline padding. */
+  --a1-button-padding-inline: var(--base-spacing-8);
+  position: relative;
+}
+
+/* Hairline divider between the two targets, drawn in the button's own foreground
+   so it reads on every variant. */
+.a1-split-button__toggle::before {
+  content: "";
+  position: absolute;
+  inset-block: var(--base-spacing-8);
+  inset-inline-start: 0;
+  inline-size: var(--component-divider-size-sm);
+  background: color-mix(in srgb, var(--a1-button-foreground) 35%, transparent);
+}
+
+.a1-split-button__caret {
+  font-size: var(--component-button-icon-size);
+}
+
+.a1-split-button--disabled {
+  cursor: not-allowed;
+}

package/src/components/toolbar/Toolbar.d.ts

@@ -0,0 +1,124 @@
+import * as React from "react";
+
+/** Standard icon name for a "none" selection. */
+export declare const TOOLBAR_NONE_ICON: string;
+
+/**
+ * Whether a tool's label is shown. Pass a boolean, or a breakpoint object to
+ * vary it responsively (cascades xs → xl, e.g. `{ xs: false, lg: true }` shows
+ * labels only from the `lg` breakpoint up). When labels can be hidden at any
+ * breakpoint the tool keeps an `aria-label`, so the accessible name is stable.
+ */
+export type ToolbarShowLabel =
+  | boolean
+  | { xs?: boolean; sm?: boolean; md?: boolean; lg?: boolean; xl?: boolean };
+
+export interface ToolbarProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Accessible name for the toolbar (ignored when `label` is set). */
+  "aria-label"?: string;
+  /**
+   * Optional visible caption rendered above the bar, styled to match the compact
+   * ChoiceGroup label. When set it also provides the toolbar's accessible name.
+   */
+  label?: React.ReactNode;
+  /**
+   * Lift the bar into a floating, elevated surface (shadow + border) for a
+   * toolbar that hovers over page content (e.g. a selection formatting bar).
+   * The consumer is responsible for positioning. Default: false
+   */
+  overlay?: boolean;
+  /**
+   * Stretch the bar to fill its container, with the tools growing to share the
+   * available width (dividers keep their natural size). When false the bar is
+   * `fit-content` wide. Default: false
+   */
+  fullWidth?: boolean;
+  children?: React.ReactNode;
+}
+/** A compact container grouping related editing controls on one subtle surface. */
+export declare function Toolbar(props: ToolbarProps): React.ReactElement;
+
+/** Visual separator between tools within a Toolbar. */
+export declare function ToolbarDivider(): React.ReactElement;
+
+export interface ToolbarToggleProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> {
+  /** Material Symbols icon name. */
+  icon?: string;
+  /** A colour swatch (any CSS color) shown inside the tool. */
+  swatch?: string;
+  /** Accessible name (and tooltip); shown as text when `showLabel`. */
+  label?: string;
+  /** Pressed (on) state. */
+  pressed?: boolean;
+  /** Called with the next pressed state when clicked. */
+  onChange?: (pressed: boolean) => void;
+  /** Show the label as visible text; boolean or a responsive breakpoint object. Default: false */
+  showLabel?: ToolbarShowLabel;
+  disabled?: boolean;
+}
+/** A two-state toggle button (e.g. bold on/off). */
+export declare function ToolbarToggle(props: ToolbarToggleProps): React.ReactElement;
+
+export interface ToolbarButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  icon?: string;
+  /** A colour swatch (any CSS color) shown inside the tool. */
+  swatch?: string;
+  /** Accessible name (and tooltip); shown as text when `showLabel`. */
+  label?: string;
+  /** Show the label as visible text; boolean or a responsive breakpoint object. Default: false */
+  showLabel?: ToolbarShowLabel;
+}
+/** A plain action button inside a Toolbar (no pressed state). */
+export declare function ToolbarButton(props: ToolbarButtonProps): React.ReactElement;
+
+export interface ToolbarMenuItem {
+  value: string | number;
+  label?: React.ReactNode;
+  /** Material Symbols icon name shown beside the menu item. */
+  icon?: string;
+  disabled?: boolean;
+}
+export interface ToolbarMenuProps {
+  /** Button icon. Defaults to the active item's icon when `value` matches one. */
+  icon?: string;
+  /** Accessible name (and tooltip); shown as text when `showLabel`. */
+  label?: string;
+  /** Currently selected value — marks the matching item active. */
+  value?: string | number;
+  /** Called with the chosen item value. */
+  onChange?: (value: string | number) => void;
+  items?: ToolbarMenuItem[];
+  /** Show the label as visible text; boolean or a responsive breakpoint object. Default: false */
+  showLabel?: ToolbarShowLabel;
+  disabled?: boolean;
+  "aria-label"?: string;
+  className?: string;
+}
+/** A toolbar button that opens a dropdown Menu of choices (e.g. list types). */
+export declare function ToolbarMenu(props: ToolbarMenuProps): React.ReactElement;
+
+export interface ToolbarGroupOption {
+  value: string | number;
+  label?: React.ReactNode;
+  /** Material Symbols icon name (rendered instead of the label in icon-only mode). */
+  icon?: string;
+  /** A colour swatch (any CSS color) shown inside the option. */
+  swatch?: string;
+  disabled?: boolean;
+}
+export interface ToolbarGroupProps {
+  value?: string | number;
+  /** Called with the newly selected option value. */
+  onChange?: (value: string | number) => void;
+  options?: ToolbarGroupOption[];
+  /** Lay the options out as a `columns`-wide grid (e.g. 3 for a 3×3 picker). */
+  columns?: number;
+  /** Show option labels as text; boolean or a responsive breakpoint object. Default: false (icon-only) */
+  showLabels?: ToolbarShowLabel;
+  "aria-label"?: string;
+  disabled?: boolean;
+  className?: string;
+}
+/** A single-select button group (radio semantics); set `columns` for a grid. */
+export declare function ToolbarGroup(props: ToolbarGroupProps): React.ReactElement;

package/src/components/toolbar/Toolbar.jsx

@@ -0,0 +1,327 @@
+import "./toolbar.css";
+import { useId, useRef, useState } from "react";
+import { Icon } from "../icon/Icon.jsx";
+import { Menu, MenuItem } from "../menu/Menu.jsx";
+
+/** Standard icon for a "none" selection (no alignment, no size, …). */
+export const TOOLBAR_NONE_ICON = "block";
+
+const BREAKPOINTS = ["xs", "sm", "md", "lg", "xl"];
+
+function cx(...parts) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function isNoneValue(v) {
+  return v === "none" || v === null || v === "";
+}
+
+/** A responsive `showLabel`/`showLabels` value: `{ xs?, sm?, … }` of booleans. */
+function isResponsive(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Is the label shown for any breakpoint? (decides whether the span renders). */
+function labelEverShown(showLabel) {
+  if (isResponsive(showLabel)) return BREAKPOINTS.some((bp) => showLabel[bp]);
+  return !!showLabel;
+}
+
+/** Are labels shown at every breakpoint? (decides icon-only fallbacks/aria). */
+function labelAlwaysShown(showLabel) {
+  return showLabel === true;
+}
+
+/** Cascade per-breakpoint visibility classes for the label span (xs → xl). */
+function labelVisibilityClasses(showLabel) {
+  if (!isResponsive(showLabel)) return [];
+  let last = false;
+  return BREAKPOINTS.map((bp) => {
+    if (typeof showLabel[bp] === "boolean") last = showLabel[bp];
+    return `a1-toolbar__label--${last ? "show" : "hide"}-${bp}`;
+  });
+}
+
+/**
+ * Accessible name for a tool button. When labels are always visible the visible
+ * text is the name (no aria-label). When they're hidden — or responsively
+ * toggled — fall back to an explicit `aria-label` so the name is stable.
+ */
+function toolAriaLabel(showLabel, label) {
+  return labelAlwaysShown(showLabel) ? undefined : label;
+}
+
+/**
+ * Toolbar — a compact container that groups related editing controls (toggles,
+ * single-select button groups, action buttons, selects, menus) on one subtle
+ * surface. Think a text-editor toolbar, or the controls in the component
+ * configurator. Compose it from the `Toolbar*` sub-components, separating tools
+ * with `<ToolbarDivider />`.
+ *
+ * Pass `label` to render an optional caption above the bar — styled to match the
+ * compact ChoiceGroup label so toolbars sit naturally alongside form controls.
+ * Pass `overlay` to lift the bar into a floating, elevated surface (shadow +
+ * border) for a toolbar that hovers over page content — e.g. a selection
+ * formatting bar. The consumer positions the overlay (the bar itself does not
+ * choose a location).
+ *
+ * By default the bar is `fit-content` wide. Pass `fullWidth` to stretch it to
+ * fill its container, with the tools growing to share the available space
+ * (dividers keep their natural size).
+ */
+export function Toolbar({
+  label,
+  overlay = false,
+  fullWidth = false,
+  "aria-label": ariaLabel,
+  className = "",
+  children,
+  ...rest
+}) {
+  const labelId = useId();
+  const bar = (
+    <div
+      role="toolbar"
+      aria-label={label ? undefined : ariaLabel}
+      aria-labelledby={label ? labelId : undefined}
+      aria-orientation="horizontal"
+      className={cx(
+        "a1-toolbar",
+        overlay && "a1-toolbar--overlay",
+        fullWidth && "a1-toolbar--full-width",
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+
+  if (!label) return bar;
+
+  return (
+    <div className="a1-toolbar-field">
+      <span className="a1-toolbar-field__label" id={labelId}>{label}</span>
+      {bar}
+    </div>
+  );
+}
+
+/** Visual separator between tools within a Toolbar. */
+export function ToolbarDivider() {
+  return <span className="a1-toolbar__divider" role="separator" aria-orientation="vertical" />;
+}
+
+function ToolButtonContent({ icon, label, showLabel, swatch }) {
+  const renderLabel = label != null && labelEverShown(showLabel);
+  const labelClass = cx("a1-toolbar__label", ...labelVisibilityClasses(showLabel));
+  return (
+    <>
+      {swatch ? <span className="a1-toolbar__swatch" style={{ background: swatch }} aria-hidden="true" /> : null}
+      {icon ? <Icon name={icon} size="sm" /> : null}
+      {renderLabel ? <span className={labelClass}>{label}</span> : null}
+    </>
+  );
+}
+
+/** A two-state toggle button (e.g. bold on/off). */
+export function ToolbarToggle({
+  icon,
+  label,
+  swatch,
+  pressed = false,
+  onChange,
+  showLabel = false,
+  disabled = false,
+  className = "",
+  ...rest
+}) {
+  return (
+    <button
+      type="button"
+      className={cx("a1-toolbar__button", className)}
+      aria-pressed={pressed}
+      aria-label={toolAriaLabel(showLabel, label)}
+      title={label}
+      disabled={disabled}
+      onClick={() => onChange?.(!pressed)}
+      {...rest}
+    >
+      <ToolButtonContent icon={icon} label={label} showLabel={showLabel} swatch={swatch} />
+    </button>
+  );
+}
+
+/** A plain action button inside a Toolbar (no pressed state). */
+export function ToolbarButton({
+  icon,
+  label,
+  swatch,
+  onClick,
+  showLabel = false,
+  disabled = false,
+  className = "",
+  ...rest
+}) {
+  return (
+    <button
+      type="button"
+      className={cx("a1-toolbar__button", className)}
+      aria-label={toolAriaLabel(showLabel, label)}
+      title={label}
+      disabled={disabled}
+      onClick={onClick}
+      {...rest}
+    >
+      <ToolButtonContent icon={icon} label={label} showLabel={showLabel} swatch={swatch} />
+    </button>
+  );
+}
+
+/**
+ * A toolbar button that opens a dropdown `Menu` of choices (e.g. a list-type
+ * picker: none / bulleted / numbered / checklist, or a text-size picker). The
+ * button carries a small
+ * caret to signal that it opens a menu. When `value` is set, the matching item
+ * is marked active and — unless an explicit `icon` is given — the button shows
+ * that item's icon so the toolbar reflects the current selection.
+ */
+export function ToolbarMenu({
+  icon,
+  label,
+  value,
+  onChange,
+  items = [],
+  showLabel = false,
+  disabled = false,
+  "aria-label": ariaLabel,
+  className = "",
+}) {
+  const [open, setOpen] = useState(false);
+  const btnRef = useRef(null);
+  const active = items.find((it) => it.value === value);
+  const buttonIcon = icon ?? active?.icon;
+  const name = ariaLabel ?? label;
+
+  return (
+    <>
+      <button
+        ref={btnRef}
+        type="button"
+        className={cx("a1-toolbar__button", "a1-toolbar__menu-button", className)}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-label={ariaLabel ?? toolAriaLabel(showLabel, label)}
+        title={label}
+        disabled={disabled}
+        onClick={() => setOpen((o) => !o)}
+      >
+        <ToolButtonContent icon={buttonIcon} label={label} showLabel={showLabel} />
+        <Icon name="arrow_drop_down" size="sm" className="a1-toolbar__caret" />
+      </button>
+      <Menu open={open} onClose={() => setOpen(false)} anchorRef={btnRef} aria-label={name}>
+        {items.map((it) => (
+          <MenuItem
+            key={String(it.value)}
+            icon={it.icon}
+            active={it.value === value}
+            disabled={it.disabled}
+            onClick={() => { onChange?.(it.value); setOpen(false); }}
+          >
+            {it.label ?? String(it.value)}
+          </MenuItem>
+        ))}
+      </Menu>
+    </>
+  );
+}
+
+/**
+ * A single-select button group (radio semantics) — e.g. text alignment, or a
+ * compact `columns`-wide grid like a 3×3 crop-direction picker. Mutually
+ * exclusive options with clearly highlighted selection, in far less space than a
+ * ChoiceGroup.
+ */
+export function ToolbarGroup({
+  value,
+  onChange,
+  options = [],
+  columns,
+  showLabels = false,
+  "aria-label": ariaLabel,
+  disabled = false,
+  className = "",
+}) {
+  const btnRefs = useRef([]);
+  const grid = typeof columns === "number" && columns > 0;
+  const selectedIndex = options.findIndex((o) => o.value === value);
+
+  function move(index, select = true) {
+    const n = options.length;
+    const idx = ((index % n) + n) % n;
+    btnRefs.current[idx]?.focus();
+    if (select) onChange?.(options[idx].value);
+  }
+
+  function handleKeyDown(e, i) {
+    const n = options.length;
+    let next = null;
+    let clampVertical = false;
+    switch (e.key) {
+      case "ArrowRight": next = i + 1; break;
+      case "ArrowLeft": next = i - 1; break;
+      case "ArrowDown": next = grid ? i + columns : i + 1; clampVertical = grid; break;
+      case "ArrowUp": next = grid ? i - columns : i - 1; clampVertical = grid; break;
+      case "Home": next = 0; break;
+      case "End": next = n - 1; break;
+      default: return;
+    }
+    e.preventDefault();
+    // Vertical moves in a grid clamp (don't wrap to a wrong column); everything
+    // else wraps around the linear order.
+    if (clampVertical) {
+      if (next < 0 || next >= n) return;
+      move(next);
+    } else {
+      move(next);
+    }
+  }
+
+  const style = grid ? { "--a1-toolbar-grid-columns": columns } : undefined;
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label={ariaLabel}
+      className={cx("a1-toolbar__group", grid && "a1-toolbar__group--grid", className)}
+      style={style}
+    >
+      {options.map((opt, i) => {
+        const selected = i === selectedIndex;
+        // Roving tabindex: the selected option (or the first, when none is
+        // selected) is the single tab stop for the group.
+        const tabIndex = selected || (selectedIndex === -1 && i === 0) ? 0 : -1;
+        const optLabel = opt.label ?? String(opt.value);
+        const icon = opt.icon ?? (!labelAlwaysShown(showLabels) && isNoneValue(opt.value) ? TOOLBAR_NONE_ICON : undefined);
+        return (
+          <button
+            key={String(opt.value)}
+            ref={(el) => { btnRefs.current[i] = el; }}
+            type="button"
+            role="radio"
+            aria-checked={selected}
+            aria-label={toolAriaLabel(showLabels, optLabel)}
+            title={optLabel}
+            tabIndex={tabIndex}
+            disabled={disabled || opt.disabled}
+            className="a1-toolbar__button"
+            onClick={() => onChange?.(opt.value)}
+            onKeyDown={(e) => handleKeyDown(e, i)}
+          >
+            <ToolButtonContent icon={icon} label={opt.label} showLabel={showLabels} swatch={opt.swatch} />
+          </button>
+        );
+      })}
+    </div>
+  );
+}