@dashforge/tw 1.0.0 → 1.1.0

package/src/components/IconButton/IconButton.tsx

@@ -0,0 +1,159 @@
+import { forwardRef, useContext } from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
+import { cn } from '../../utils/cn.js';
+import { useAccessState } from '../../hooks/useAccessState.js';
+import { buttonVariants } from '../Button/button.variants.js';
+import { Spinner } from '../Spinner/Spinner.js';
+import type { SpinnerSize } from '../Spinner/spinner.types.js';
+import {
+  ICON_BUTTON_BASE,
+  ICON_BUTTON_SIZE_OVERRIDES,
+} from './iconButton.variants.js';
+import type { IconButtonProps } from './iconButton.types.js';
+
+/**
+ * Map IconButton size to Spinner size. Same mapping as Button —
+ * Spinner has 5 steps, the parent has 3.
+ *
+ * @internal
+ */
+function iconButtonSizeToSpinnerSize(size: 'sm' | 'md' | 'lg'): SpinnerSize {
+  return size === 'sm' ? 'xs' : size === 'lg' ? 'md' : 'sm';
+}
+
+/**
+ * Dashforge TW IconButton — square, icon-only action button.
+ *
+ * Reuses `buttonVariants` 1:1 (same `variant` / `color` / `size` /
+ * `loading` axes) so every `<Button>` style maps to the equivalent
+ * `<IconButton>` with zero code duplication. The ONLY additions are:
+ *
+ *   - `ICON_BUTTON_SIZE_OVERRIDES` — forces `w-N + px-0` so the button
+ *     is square at every size token
+ *   - `ICON_BUTTON_BASE` — `aspect-square inline-flex items-center
+ *     justify-center` for layout
+ *
+ * Both additions are token-driven (spacing) or layout-primitive
+ * (geometry) — no hardcoded hex, no `dark:` variants.
+ *
+ * **`aria-label` is REQUIRED** at the type level — icon-only buttons
+ * are invisible to assistive tech without an explicit accessible
+ * name. The TypeScript compiler enforces this rather than relying on
+ * runtime warnings.
+ *
+ * RBAC integration mirrors `<Button>`: `access` with
+ * `onUnauthorized: 'hide' | 'disable' | 'readonly'`. No `visibleWhen`
+ * (mirror Button — buttons should disable, not hide, on
+ * state-driven unavailability; permission-driven hiding is `access`).
+ *
+ * @example
+ * ```tsx
+ * import { Trash2 } from 'lucide-react';
+ *
+ * <IconButton aria-label="Delete row" color="danger" onClick={onDelete}>
+ *   <Trash2 size={20} />
+ * </IconButton>
+ *
+ * // Polymorphism via Radix Slot
+ * <IconButton asChild aria-label="Open settings" variant="ghost">
+ *   <Link to="/settings"><SettingsIcon size={20} /></Link>
+ * </IconButton>
+ *
+ * // RBAC-gated
+ * <IconButton
+ *   aria-label="Publish article"
+ *   variant="solid"
+ *   color="primary"
+ *   access={{ resource: 'article', action: 'publish', onUnauthorized: 'disable' }}
+ * >
+ *   <PublishIcon size={20} />
+ * </IconButton>
+ *
+ * // Loading swap
+ * <IconButton aria-label="Save" loading={isSaving}>
+ *   <SaveIcon size={20} />
+ * </IconButton>
+ * ```
+ */
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
+  function IconButton(props, ref) {
+    const {
+      access,
+      visibleWhen,
+      disabled,
+      variant,
+      color,
+      size = 'md',
+      loading,
+      asChild,
+      sx,
+      className,
+      children,
+      ...rest
+    } = props;
+
+    // Bridge — both hooks called unconditionally (rules-of-hooks).
+    const bridge = useContext(DashFormContext);
+    const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
+    const accessState = useAccessState(access);
+    if (!isVisible || !accessState.visible) return null;
+
+    // Effective disabled = explicit OR RBAC.disabled OR RBAC.readonly OR loading.
+    // Mirrors `<Button>` exactly — IconButton has no true read-only
+    // state, so RBAC readonly maps to disabled (same as MUI side).
+    const effectiveDisabled =
+      Boolean(disabled) ||
+      accessState.disabled ||
+      accessState.readonly ||
+      Boolean(loading);
+
+    const classes = cn(
+      buttonVariants({ variant, color, size, loading }),
+      ICON_BUTTON_SIZE_OVERRIDES[size],
+      ICON_BUTTON_BASE,
+      sx,
+      className
+    );
+
+    // `aria-busy` while loading — distinguishes "wait for action to
+    // finish" from "you can't do this" in screen-reader announcements.
+    const ariaBusy = loading ? true : undefined;
+
+    if (asChild) {
+      return (
+        <Slot
+          ref={ref}
+          className={classes}
+          data-disabled={effectiveDisabled || undefined}
+          aria-disabled={effectiveDisabled || undefined}
+          aria-busy={ariaBusy}
+        >
+          {children}
+        </Slot>
+      );
+    }
+
+    return (
+      <button
+        ref={ref}
+        type={rest.type ?? 'button'}
+        disabled={effectiveDisabled}
+        aria-busy={ariaBusy}
+        className={classes}
+        {...rest}
+      >
+        {loading ? (
+          <Spinner
+            size={iconButtonSizeToSpinnerSize(size)}
+            thickness="thick"
+            withTrack
+            label=""
+          />
+        ) : (
+          children
+        )}
+      </button>
+    );
+  }
+);

package/src/components/IconButton/iconButton.types.ts

@@ -0,0 +1,106 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+import type { ClassValue } from 'tailwind-variants';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { ButtonVariants } from '../Button/button.variants.js';
+
+/**
+ * Props for `<IconButton>`.
+ *
+ * IconButton is the **icon-only variant of `<Button>`** — it reuses
+ * `buttonVariants` 1:1 (same `variant` × `color` × `size` × `loading`
+ * compound matrix) and adds:
+ *
+ *   - Square geometry (width = height = size token, `aspect-square`)
+ *   - Zero horizontal padding (no text to pad around)
+ *   - **`aria-label` REQUIRED** at the type level — icon-only buttons
+ *     are invisible to screen readers without an explicit label, so we
+ *     enforce it via TypeScript rather than runtime warning.
+ *
+ * Notes on excluded props (deliberate parity with `<Button>`):
+ *   - **No `slotProps`** — IconButton renders a single DOM element
+ *     (`<button>` plus a transient loading swap); `className` + `sx`
+ *     cover the override surface fully, matching Button.
+ *   - **No `fullWidth`** — meaningless on an icon-sized button.
+ *
+ * As of 1.1.0 (Sprint 4.4 alignment), IconButton + Button both
+ * support `visibleWhen` — see prop docs below.
+ *
+ * @example
+ * ```tsx
+ * import { TrashIcon } from 'lucide-react';
+ *
+ * <IconButton aria-label="Delete row" color="danger" onClick={onDelete}>
+ *   <TrashIcon size={20} />
+ * </IconButton>
+ *
+ * // Polymorphism via Radix Slot — wrap a router Link without nesting
+ * // a button inside an anchor.
+ * <IconButton asChild aria-label="Open settings" variant="ghost">
+ *   <Link to="/settings"><SettingsIcon size={20} /></Link>
+ * </IconButton>
+ *
+ * // RBAC-gated
+ * <IconButton
+ *   aria-label="Publish article"
+ *   variant="solid"
+ *   color="primary"
+ *   access={{ resource: 'article', action: 'publish', onUnauthorized: 'disable' }}
+ * >
+ *   <PublishIcon size={20} />
+ * </IconButton>
+ * ```
+ */
+export interface IconButtonProps
+  extends Omit<
+      ButtonHTMLAttributes<HTMLButtonElement>,
+      'color' | 'children'
+    >,
+    Pick<ButtonVariants, 'variant' | 'color' | 'size' | 'loading'> {
+  /**
+   * The icon — typically an SVG element from the consumer's icon
+   * library (Lucide / Phosphor / Tabler / inline SVG). A single
+   * `ReactNode` is expected.
+   */
+  children: ReactNode;
+
+  /**
+   * Required at the type level — icon-only buttons MUST have an
+   * accessible name. Pass a short verb phrase describing the action
+   * (e.g. `"Delete row"`, `"Open settings"`, NOT `"Trash icon"`).
+   */
+  'aria-label': string;
+
+  /**
+   * Render-as-child via Radix Slot — the resolved IconButton
+   * className is forwarded to the immediate child element, no
+   * `<button>` DOM is emitted. Useful for router `<Link>`s.
+   * Same contract as `<Button asChild>`.
+   */
+  asChild?: boolean;
+
+  /**
+   * RBAC requirement. When the current subject doesn't satisfy the
+   * requirement, the button is hidden / disabled / read-only per
+   * `onUnauthorized`. Same contract as `<Button access>`.
+   */
+  access?: AccessRequirement;
+
+  /**
+   * Reactive visibility predicate — same contract as `<Button>` and
+   * `<Chip>`. When the predicate returns `false`, the component
+   * renders `null`. Inside a `<DashForm>` it subscribes to engine
+   * state and re-evaluates on every change; outside a form, it's
+   * called with `null` engine (capture external state in closure).
+   *
+   * Added in 1.1.0 (Sprint 4.4 alignment) to keep IconButton in
+   * lockstep with Button.
+   */
+  visibleWhen?: (engine: Engine) => boolean;
+
+  /**
+   * Root-element class shortcut (string or `clsx`-compatible value).
+   * Last-wins via `tailwind-merge` inside `cn()`.
+   */
+  sx?: ClassValue;
+}

package/src/components/IconButton/iconButton.variants.ts

@@ -0,0 +1,31 @@
+import type { ButtonVariants } from '../Button/button.variants.js';
+
+/**
+ * IconButton size overrides — applied ON TOP of `buttonVariants(...)`.
+ *
+ * Button's `size` axis sets `h-X` + `px-Y` (rectangular). For
+ * IconButton we need a SQUARE shape, so we:
+ *   - zero out the horizontal padding (`px-0`)
+ *   - set an explicit width that matches the height (`w-N` mirrors the
+ *     `h-N` from Button's size variant)
+ *
+ * The `aspect-square` utility provides belt-and-braces in the edge
+ * case where Tailwind purges the explicit `w-N` (e.g., when the user
+ * passes `size` dynamically and the JIT can't statically see all
+ * combinations).
+ *
+ * Token propagation: `w-N` resolves to `var(--df-tw-spacing-N)`
+ * through `dashforgePreset()`, identical to how `h-N` works for
+ * Button. `patchTheme({ spacing: { 10: '2.75rem' } })` patches both
+ * Button height and IconButton size in lockstep.
+ */
+type IconButtonSize = NonNullable<ButtonVariants['size']>;
+
+export const ICON_BUTTON_SIZE_OVERRIDES: Record<IconButtonSize, string> = {
+  sm: 'w-8 px-0',
+  md: 'w-10 px-0',
+  lg: 'w-12 px-0',
+};
+
+/** Always-applied layout primitives — not token-driven (geometric CSS). */
+export const ICON_BUTTON_BASE = 'aspect-square inline-flex items-center justify-center';

package/src/components/LeftNav/leftNav.variants.ts

@@ -33,7 +33,7 @@ export const leftNavVariants = tv({
       'flex items-center gap-2 px-3 h-14 shrink-0',
       'border-b border-neutral-200 text-neutral-900 font-semibold',
     ],
-    list: 'flex flex-col gap-0.5 p-2 flex-1 overflow-y-auto',
+    list: 'flex flex-col gap-0.5 p-2 flex-1 overflow-y-auto list-none m-0',
     item: 'list-none',
     itemLink: [
       'flex items-center gap-2 px-2 py-2 rounded-md',
@@ -66,7 +66,7 @@ export const leftNavVariants = tv({
       'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
       'transition-colors w-full',
     ],
-    groupChildren: 'flex flex-col gap-0.5 pl-6',
+    groupChildren: 'flex flex-col gap-0.5 pl-6 list-none m-0',
     footer: [
       'border-t border-neutral-200 p-3 shrink-0',
       'flex items-center gap-2',