@better-forge/ui 0.1.0 → 0.1.1

package/src/components/ui/Pagination.tsx

@@ -1,37 +1,37 @@
-import type { ReactNode } from 'react'
-
-type PaginationProps = {
-  /** 1-based current page. */
-  page: number
-  onPageChange: (page: number) => void
-  /** Text on the left, e.g. "Page 2 of 5 · 93 entries". Defaults to "Page X of Y" when pageCount is known. */
-  summary?: ReactNode | undefined
-  /** Hide the whole bar when there is only one page (default true; ignored with hasNext). */
-  hideWhenSingle?: boolean | undefined
-} & (
-  | { pageCount: number; hasNext?: never }
-  /** For cursor/unknown-total lists: whether a next page exists. */
-  | { hasNext: boolean; pageCount?: never }
-)
-
-export function Pagination({ page, onPageChange, summary, hideWhenSingle = true, pageCount, hasNext }: PaginationProps) {
-  const canPrev = page > 1
-  const canNext = pageCount !== undefined ? page < pageCount : Boolean(hasNext)
-  if (pageCount !== undefined && hideWhenSingle && pageCount <= 1) return null
-
-  const text = summary ?? (pageCount !== undefined ? `Page ${page} of ${pageCount}` : `Page ${page}`)
-
-  return (
-    <nav aria-label="Pagination" className="flex flex-wrap items-center justify-between gap-3">
-      <span className="text-sm" style={{ color: 'var(--m3-secondary)' }}>{text}</span>
-      <div className="flex gap-2">
-        <button type="button" onClick={() => onPageChange(page - 1)} disabled={!canPrev} aria-label="Previous page" className="btn btn-outline btn-sm text-sm font-normal">
-          ← Prev
-        </button>
-        <button type="button" onClick={() => onPageChange(page + 1)} disabled={!canNext} aria-label="Next page" className="btn btn-outline btn-sm text-sm font-normal">
-          Next →
-        </button>
-      </div>
-    </nav>
-  )
-}
+import type { ReactNode } from 'react'
+
+type PaginationProps = {
+  /** 1-based current page. */
+  page: number
+  onPageChange: (page: number) => void
+  /** Text on the left, e.g. "Page 2 of 5 · 93 entries". Defaults to "Page X of Y" when pageCount is known. */
+  summary?: ReactNode | undefined
+  /** Hide the whole bar when there is only one page (default true; ignored with hasNext). */
+  hideWhenSingle?: boolean | undefined
+} & (
+  | { pageCount: number; hasNext?: never }
+  /** For cursor/unknown-total lists: whether a next page exists. */
+  | { hasNext: boolean; pageCount?: never }
+)
+
+export function Pagination({ page, onPageChange, summary, hideWhenSingle = true, pageCount, hasNext }: PaginationProps) {
+  const canPrev = page > 1
+  const canNext = pageCount !== undefined ? page < pageCount : Boolean(hasNext)
+  if (pageCount !== undefined && hideWhenSingle && pageCount <= 1) return null
+
+  const text = summary ?? (pageCount !== undefined ? `Page ${page} of ${pageCount}` : `Page ${page}`)
+
+  return (
+    <nav aria-label="Pagination" className="flex flex-wrap items-center justify-between gap-3">
+      <span className="text-sm" style={{ color: 'var(--m3-secondary)' }}>{text}</span>
+      <div className="flex gap-2">
+        <button type="button" onClick={() => onPageChange(page - 1)} disabled={!canPrev} aria-label="Previous page" className="btn btn-outline btn-sm text-sm font-normal">
+          ← Prev
+        </button>
+        <button type="button" onClick={() => onPageChange(page + 1)} disabled={!canNext} aria-label="Next page" className="btn btn-outline btn-sm text-sm font-normal">
+          Next →
+        </button>
+      </div>
+    </nav>
+  )
+}

package/src/components/ui/QuickStartPanel.tsx

@@ -1,57 +1,57 @@
-import { useId, type ReactNode } from 'react'
-
-export interface QuickStartOption<K extends string> {
-  key: K
-  label: string
-  hint: string
-  /** Icon element (a Material Symbol or a brand glyph), rendered inside the tile's icon chip. */
-  icon: ReactNode
-}
-
-interface QuickStartPanelProps<K extends string> {
-  title: string
-  description?: ReactNode | undefined
-  options: QuickStartOption<K>[]
-  onPick: (key: K) => void
-}
-
-/**
- * First-run panel shown in place of an empty list when the first step is a choice, e.g. which kind of
- * channel to create. Each tile starts the create flow with that choice already made.
- */
-export function QuickStartPanel<K extends string>({ title, description, options, onPick }: QuickStartPanelProps<K>) {
-  const titleId = useId()
-  return (
-    <section
-      aria-labelledby={titleId}
-      className="rounded-2xl p-5 space-y-4"
-      style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}
-    >
-      <div className="space-y-0.5">
-        <h2 id={titleId} className="font-headline font-semibold text-[15px]" style={{ color: 'var(--m3-on-surface)' }}>{title}</h2>
-        {description && <p className="text-[13px]" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
-      </div>
-      <ul className="grid gap-2.5 grid-cols-[repeat(auto-fill,minmax(150px,1fr))]">
-        {options.map((option) => (
-          <li key={option.key}>
-            <button
-              type="button"
-              onClick={() => onPick(option.key)}
-              className="w-full h-full grid gap-2 content-start text-left rounded-[14px] p-3.5 border border-outline-variant bg-surface text-on-surface hover:border-outline hover:bg-surface-container-lowest motion-safe:transition-colors focus-ring"
-            >
-              <span
-                className="grid place-items-center w-[34px] h-[34px] rounded-[10px]"
-                aria-hidden="true"
-                style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}
-              >
-                {option.icon}
-              </span>
-              <span className="text-[13px] font-semibold">{option.label}</span>
-              <span className="text-xs" style={{ color: 'var(--m3-secondary)' }}>{option.hint}</span>
-            </button>
-          </li>
-        ))}
-      </ul>
-    </section>
-  )
-}
+import { useId, type ReactNode } from 'react'
+
+export interface QuickStartOption<K extends string> {
+  key: K
+  label: string
+  hint: string
+  /** Icon element (a Material Symbol or a brand glyph), rendered inside the tile's icon chip. */
+  icon: ReactNode
+}
+
+interface QuickStartPanelProps<K extends string> {
+  title: string
+  description?: ReactNode | undefined
+  options: QuickStartOption<K>[]
+  onPick: (key: K) => void
+}
+
+/**
+ * First-run panel shown in place of an empty list when the first step is a choice, e.g. which kind of
+ * channel to create. Each tile starts the create flow with that choice already made.
+ */
+export function QuickStartPanel<K extends string>({ title, description, options, onPick }: QuickStartPanelProps<K>) {
+  const titleId = useId()
+  return (
+    <section
+      aria-labelledby={titleId}
+      className="rounded-2xl p-5 space-y-4"
+      style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}
+    >
+      <div className="space-y-0.5">
+        <h2 id={titleId} className="font-headline font-semibold text-[15px]" style={{ color: 'var(--m3-on-surface)' }}>{title}</h2>
+        {description && <p className="text-[13px]" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
+      </div>
+      <ul className="grid gap-2.5 grid-cols-[repeat(auto-fill,minmax(150px,1fr))]">
+        {options.map((option) => (
+          <li key={option.key}>
+            <button
+              type="button"
+              onClick={() => onPick(option.key)}
+              className="w-full h-full grid gap-2 content-start text-left rounded-[14px] p-3.5 border border-outline-variant bg-surface text-on-surface hover:border-outline hover:bg-surface-container-lowest motion-safe:transition-colors focus-ring"
+            >
+              <span
+                className="grid place-items-center w-[34px] h-[34px] rounded-[10px]"
+                aria-hidden="true"
+                style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}
+              >
+                {option.icon}
+              </span>
+              <span className="text-[13px] font-semibold">{option.label}</span>
+              <span className="text-xs" style={{ color: 'var(--m3-secondary)' }}>{option.hint}</span>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}

package/src/components/ui/StateViews.tsx

@@ -1,135 +1,135 @@
-import clsx from 'clsx'
-import type { CSSProperties, ReactNode } from 'react'
-
-interface LoadingStateProps {
-  label?: string | undefined
-  className?: string | undefined
-}
-
-/** Centered spinner with a caption for data that is still loading. */
-export function LoadingState({ label = 'Loading…', className }: LoadingStateProps) {
-  return (
-    <div role="status" aria-live="polite" className={clsx('flex items-center justify-center gap-3 py-12 text-sm', className)} style={{ color: 'var(--m3-secondary)' }}>
-      <span className="material-symbols-outlined animate-spin" aria-hidden="true" style={{ fontSize: '20px' }}>progress_activity</span>
-      <span>{label}</span>
-    </div>
-  )
-}
-
-interface ErrorStateProps {
-  message?: ReactNode | undefined
-  /** Renders a "Try again" button. Pass e.g. `() => void query.refetch()`. */
-  onRetry?: (() => void) | undefined
-  className?: string | undefined
-}
-
-/** Failed-to-load panel with an optional retry action. */
-export function ErrorState({ message = 'Something went wrong while loading this data.', onRetry, className }: ErrorStateProps) {
-  return (
-    <div
-      role="alert"
-      className={clsx('flex flex-col items-center justify-center gap-3 rounded-2xl px-6 py-10 text-center', className)}
-      style={{ background: 'var(--m3-down-bg)', color: 'var(--m3-down)' }}
-    >
-      <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: '28px' }}>error</span>
-      <p className="text-sm max-w-md">{message}</p>
-      {onRetry && (
-        <button type="button" onClick={onRetry} className="btn btn-secondary btn-sm">
-          <span className="material-symbols-outlined" aria-hidden="true">refresh</span>
-          Try again
-        </button>
-      )}
-    </div>
-  )
-}
-
-type EmptyStateVariant = 'card' | 'inset' | 'row'
-
-interface EmptyStateProps {
-  title: ReactNode
-  description?: ReactNode | undefined
-  /** Material Symbols icon name, e.g. "radio_button_checked". */
-  icon?: string | undefined
-  /**
-   * Optional follow-up action. Leave it out when the page header already offers the same action and
-   * put an `EmptyStateLink` in the description instead.
-   */
-  action?: ReactNode | undefined
-  /**
-   * - `card` (default): a standalone compact strip, for pages without a table or list container.
-   * - `inset`: a row inside a card or list, separated from what is above it by a divider.
-   * - `row`: bare content for a table cell; use `EmptyTableRow` rather than this directly.
-   */
-  variant?: EmptyStateVariant | undefined
-  className?: string | undefined
-}
-
-const EMPTY_VARIANT_CLASS: Record<EmptyStateVariant, string> = {
-  card: 'rounded-2xl px-5 py-4',
-  inset: 'px-6 py-5',
-  row: '',
-}
-
-const EMPTY_VARIANT_STYLE: Record<EmptyStateVariant, CSSProperties | undefined> = {
-  card: { background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' },
-  inset: { borderTop: '1px solid var(--m3-outline-variant)' },
-  row: undefined,
-}
-
-/** Compact placeholder for an empty list: an icon, a short explanation and an optional action in one row. */
-export function EmptyState({ title, description, icon = 'inbox', action, variant = 'card', className }: EmptyStateProps) {
-  return (
-    <div
-      className={clsx('flex flex-wrap items-center gap-x-3.5 gap-y-3 text-left', EMPTY_VARIANT_CLASS[variant], className)}
-      style={EMPTY_VARIANT_STYLE[variant]}
-    >
-      <span
-        className="grid place-items-center w-10 h-10 rounded-xl flex-none"
-        aria-hidden="true"
-        style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}
-      >
-        <span className="material-symbols-outlined" style={{ fontSize: '20px' }}>{icon}</span>
-      </span>
-      <div className="min-w-0 flex-[1_1_15rem] space-y-0.5">
-        <p className="font-headline font-semibold text-sm" style={{ color: 'var(--m3-on-surface)' }}>{title}</p>
-        {description && <p className="text-[13px]" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
-      </div>
-      {action && <div className="flex-none sm:ml-auto">{action}</div>}
-    </div>
-  )
-}
-
-interface EmptyTableRowProps extends Omit<EmptyStateProps, 'variant' | 'className'> {
-  /** Number of columns in the table, so the message spans the whole row. */
-  colSpan: number
-}
-
-/** The only `<tbody>` row while a table has no data, so the table and its headers keep their place. */
-export function EmptyTableRow({ colSpan, ...props }: EmptyTableRowProps) {
-  return (
-    <tr>
-      <td colSpan={colSpan} className="px-4 py-7">
-        <EmptyState variant="row" {...props} />
-      </td>
-    </tr>
-  )
-}
-
-interface EmptyStateLinkProps {
-  onClick: () => void
-  children: ReactNode
-}
-
-/** Inline text action inside an empty-state description, e.g. "Alerts stay silent until you [add a channel]." */
-export function EmptyStateLink({ onClick, children }: EmptyStateLinkProps) {
-  return (
-    <button
-      type="button"
-      onClick={onClick}
-      className="font-semibold underline underline-offset-[3px] rounded focus-ring"
-      style={{ color: 'var(--m3-on-surface)' }}
-    >
-      {children}
-    </button>
-  )
-}
+import clsx from 'clsx'
+import type { CSSProperties, ReactNode } from 'react'
+
+interface LoadingStateProps {
+  label?: string | undefined
+  className?: string | undefined
+}
+
+/** Centered spinner with a caption for data that is still loading. */
+export function LoadingState({ label = 'Loading…', className }: LoadingStateProps) {
+  return (
+    <div role="status" aria-live="polite" className={clsx('flex items-center justify-center gap-3 py-12 text-sm', className)} style={{ color: 'var(--m3-secondary)' }}>
+      <span className="material-symbols-outlined animate-spin" aria-hidden="true" style={{ fontSize: '20px' }}>progress_activity</span>
+      <span>{label}</span>
+    </div>
+  )
+}
+
+interface ErrorStateProps {
+  message?: ReactNode | undefined
+  /** Renders a "Try again" button. Pass e.g. `() => void query.refetch()`. */
+  onRetry?: (() => void) | undefined
+  className?: string | undefined
+}
+
+/** Failed-to-load panel with an optional retry action. */
+export function ErrorState({ message = 'Something went wrong while loading this data.', onRetry, className }: ErrorStateProps) {
+  return (
+    <div
+      role="alert"
+      className={clsx('flex flex-col items-center justify-center gap-3 rounded-2xl px-6 py-10 text-center', className)}
+      style={{ background: 'var(--m3-down-bg)', color: 'var(--m3-down)' }}
+    >
+      <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: '28px' }}>error</span>
+      <p className="text-sm max-w-md">{message}</p>
+      {onRetry && (
+        <button type="button" onClick={onRetry} className="btn btn-secondary btn-sm">
+          <span className="material-symbols-outlined" aria-hidden="true">refresh</span>
+          Try again
+        </button>
+      )}
+    </div>
+  )
+}
+
+type EmptyStateVariant = 'card' | 'inset' | 'row'
+
+interface EmptyStateProps {
+  title: ReactNode
+  description?: ReactNode | undefined
+  /** Material Symbols icon name, e.g. "radio_button_checked". */
+  icon?: string | undefined
+  /**
+   * Optional follow-up action. Leave it out when the page header already offers the same action and
+   * put an `EmptyStateLink` in the description instead.
+   */
+  action?: ReactNode | undefined
+  /**
+   * - `card` (default): a standalone compact strip, for pages without a table or list container.
+   * - `inset`: a row inside a card or list, separated from what is above it by a divider.
+   * - `row`: bare content for a table cell; use `EmptyTableRow` rather than this directly.
+   */
+  variant?: EmptyStateVariant | undefined
+  className?: string | undefined
+}
+
+const EMPTY_VARIANT_CLASS: Record<EmptyStateVariant, string> = {
+  card: 'rounded-2xl px-5 py-4',
+  inset: 'px-6 py-5',
+  row: '',
+}
+
+const EMPTY_VARIANT_STYLE: Record<EmptyStateVariant, CSSProperties | undefined> = {
+  card: { background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' },
+  inset: { borderTop: '1px solid var(--m3-outline-variant)' },
+  row: undefined,
+}
+
+/** Compact placeholder for an empty list: an icon, a short explanation and an optional action in one row. */
+export function EmptyState({ title, description, icon = 'inbox', action, variant = 'card', className }: EmptyStateProps) {
+  return (
+    <div
+      className={clsx('flex flex-wrap items-center gap-x-3.5 gap-y-3 text-left', EMPTY_VARIANT_CLASS[variant], className)}
+      style={EMPTY_VARIANT_STYLE[variant]}
+    >
+      <span
+        className="grid place-items-center w-10 h-10 rounded-xl flex-none"
+        aria-hidden="true"
+        style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}
+      >
+        <span className="material-symbols-outlined" style={{ fontSize: '20px' }}>{icon}</span>
+      </span>
+      <div className="min-w-0 flex-[1_1_15rem] space-y-0.5">
+        <p className="font-headline font-semibold text-sm" style={{ color: 'var(--m3-on-surface)' }}>{title}</p>
+        {description && <p className="text-[13px]" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
+      </div>
+      {action && <div className="flex-none sm:ml-auto">{action}</div>}
+    </div>
+  )
+}
+
+interface EmptyTableRowProps extends Omit<EmptyStateProps, 'variant' | 'className'> {
+  /** Number of columns in the table, so the message spans the whole row. */
+  colSpan: number
+}
+
+/** The only `<tbody>` row while a table has no data, so the table and its headers keep their place. */
+export function EmptyTableRow({ colSpan, ...props }: EmptyTableRowProps) {
+  return (
+    <tr>
+      <td colSpan={colSpan} className="px-4 py-7">
+        <EmptyState variant="row" {...props} />
+      </td>
+    </tr>
+  )
+}
+
+interface EmptyStateLinkProps {
+  onClick: () => void
+  children: ReactNode
+}
+
+/** Inline text action inside an empty-state description, e.g. "Alerts stay silent until you [add a channel]." */
+export function EmptyStateLink({ onClick, children }: EmptyStateLinkProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="font-semibold underline underline-offset-[3px] rounded focus-ring"
+      style={{ color: 'var(--m3-on-surface)' }}
+    >
+      {children}
+    </button>
+  )
+}

package/src/components/ui/Switch.tsx

@@ -1,65 +1,65 @@
-import clsx from 'clsx'
-import { useId, type ReactNode } from 'react'
-
-interface SwitchProps {
-  checked: boolean
-  onChange: (checked: boolean) => void
-  /** Visible label; clicking it toggles the switch. Without it pass `aria-label`. */
-  label?: ReactNode | undefined
-  description?: ReactNode | undefined
-  disabled?: boolean | undefined
-  id?: string | undefined
-  'aria-label'?: string | undefined
-  className?: string | undefined
-}
-
-/** On/off toggle rendered as <button role="switch">, optionally with a clickable label and a description. */
-export function Switch({ checked, onChange, label, description, disabled = false, id, 'aria-label': ariaLabel, className }: SwitchProps) {
-  const generatedId = useId()
-  const switchId = id ?? generatedId
-  const labelId = `${switchId}-label`
-  const descriptionId = `${switchId}-description`
-
-  const control = (
-    <button
-      id={switchId}
-      type="button"
-      role="switch"
-      aria-checked={checked}
-      aria-label={label ? undefined : ariaLabel}
-      aria-labelledby={label ? labelId : undefined}
-      aria-describedby={description ? descriptionId : undefined}
-      disabled={disabled}
-      onClick={() => onChange(!checked)}
-      className="relative flex-shrink-0 w-12 h-7 rounded-full transition-colors focus-ring disabled:opacity-50 disabled:cursor-not-allowed"
-      style={{ background: checked ? 'var(--admin-control-accent)' : 'var(--m3-outline-variant)' }}
-    >
-      <span
-        aria-hidden="true"
-        className="absolute top-1 w-5 h-5 rounded-full transition-all"
-        style={{ left: checked ? '24px' : '4px', background: checked ? 'var(--admin-control-on)' : 'var(--m3-outline)' }}
-      />
-    </button>
-  )
-
-  if (!label && !description) return <span className={clsx('inline-flex', className)}>{control}</span>
-
-  return (
-    <div className={clsx('flex items-start justify-between gap-4', className)}>
-      <div className="min-w-0">
-        {label && (
-          <label
-            id={labelId}
-            htmlFor={switchId}
-            className={clsx('block text-sm font-medium', disabled ? 'cursor-not-allowed' : 'cursor-pointer')}
-            style={{ color: 'var(--m3-on-surface)' }}
-          >
-            {label}
-          </label>
-        )}
-        {description && <p id={descriptionId} className="text-xs mt-0.5" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
-      </div>
-      {control}
-    </div>
-  )
-}
+import clsx from 'clsx'
+import { useId, type ReactNode } from 'react'
+
+interface SwitchProps {
+  checked: boolean
+  onChange: (checked: boolean) => void
+  /** Visible label; clicking it toggles the switch. Without it pass `aria-label`. */
+  label?: ReactNode | undefined
+  description?: ReactNode | undefined
+  disabled?: boolean | undefined
+  id?: string | undefined
+  'aria-label'?: string | undefined
+  className?: string | undefined
+}
+
+/** On/off toggle rendered as <button role="switch">, optionally with a clickable label and a description. */
+export function Switch({ checked, onChange, label, description, disabled = false, id, 'aria-label': ariaLabel, className }: SwitchProps) {
+  const generatedId = useId()
+  const switchId = id ?? generatedId
+  const labelId = `${switchId}-label`
+  const descriptionId = `${switchId}-description`
+
+  const control = (
+    <button
+      id={switchId}
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      aria-label={label ? undefined : ariaLabel}
+      aria-labelledby={label ? labelId : undefined}
+      aria-describedby={description ? descriptionId : undefined}
+      disabled={disabled}
+      onClick={() => onChange(!checked)}
+      className="relative flex-shrink-0 w-12 h-7 rounded-full transition-colors focus-ring disabled:opacity-50 disabled:cursor-not-allowed"
+      style={{ background: checked ? 'var(--admin-control-accent)' : 'var(--m3-outline-variant)' }}
+    >
+      <span
+        aria-hidden="true"
+        className="absolute top-1 w-5 h-5 rounded-full transition-all"
+        style={{ left: checked ? '24px' : '4px', background: checked ? 'var(--admin-control-on)' : 'var(--m3-outline)' }}
+      />
+    </button>
+  )
+
+  if (!label && !description) return <span className={clsx('inline-flex', className)}>{control}</span>
+
+  return (
+    <div className={clsx('flex items-start justify-between gap-4', className)}>
+      <div className="min-w-0">
+        {label && (
+          <label
+            id={labelId}
+            htmlFor={switchId}
+            className={clsx('block text-sm font-medium', disabled ? 'cursor-not-allowed' : 'cursor-pointer')}
+            style={{ color: 'var(--m3-on-surface)' }}
+          >
+            {label}
+          </label>
+        )}
+        {description && <p id={descriptionId} className="text-xs mt-0.5" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
+      </div>
+      {control}
+    </div>
+  )
+}