@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/forms/CredentialDisclosureDialog/examples/ResponseGating.tsx

@@ -0,0 +1,69 @@
+import { Alert, Button } from '@gntik-ai/ui';
+import { useRef, useState } from 'react';
+import { CredentialDisclosureDialog, type CredentialDisclosure } from '../CredentialDisclosureDialog';
+import { storedDisclosure } from '../fixtures';
+
+/** Pending/error UI belongs to the consumer; only a successful response sets disclosure. */
+export default function ResponseGating() {
+  const [disclosure, setDisclosure] = useState<CredentialDisclosure | null>(null);
+  const [status, setStatus] = useState<'idle' | 'pending' | 'failed'>('idle');
+  const heading = useRef<HTMLHeadingElement>(null);
+  const requestId = useRef(0);
+  const request = async (result: 'pending' | 'failed' | 'success') => {
+    const id = ++requestId.current;
+    setDisclosure(null);
+    setStatus('pending');
+    try {
+      const response = await (result === 'pending'
+        ? new Promise<CredentialDisclosure>(() => {})
+        : result === 'failed'
+          ? Promise.reject(new Error('Synthetic request failure'))
+          : Promise.resolve(storedDisclosure));
+      if (id === requestId.current) {
+        setStatus('idle');
+        setDisclosure(response);
+      }
+    } catch {
+      if (id === requestId.current) setStatus('failed');
+    }
+  };
+  return (
+    <>
+      <h1 ref={heading} tabIndex={-1}>
+        Credentials
+      </h1>
+      <div className="flex flex-wrap gap-2">
+        <Button
+          onClick={() => {
+            void request('pending');
+          }}
+        >
+          Request pending response
+        </Button>
+        <Button
+          onClick={() => {
+            void request('failed');
+          }}
+        >
+          Request rejected response
+        </Button>
+        <Button
+          onClick={() => {
+            void request('success');
+          }}
+        >
+          Request successful response
+        </Button>
+      </div>
+      {status === 'pending' && <p>Request pending</p>}
+      {status === 'failed' && (
+        <Alert tone="destructive" title="Request failed" description="No credential was disclosed." />
+      )}
+      <CredentialDisclosureDialog
+        disclosure={disclosure}
+        onClose={() => setDisclosure(null)}
+        fallbackFocus={() => heading.current}
+      />
+    </>
+  );
+}

package/src/forms/CredentialDisclosureDialog/examples/Stored.tsx

@@ -0,0 +1,32 @@
+import { Button } from '@gntik-ai/ui';
+import { useRef, useState } from 'react';
+import { CredentialDisclosureDialog, type CredentialDisclosure } from '../CredentialDisclosureDialog';
+import { storedDisclosure } from '../fixtures';
+
+/** The initial synthetic stored value stays masked in catalog previews and visual baselines. */
+export default function Stored() {
+  const [disclosure, setDisclosure] = useState<CredentialDisclosure | null>(storedDisclosure);
+  const heading = useRef<HTMLHeadingElement>(null);
+  const trigger = useRef<HTMLButtonElement>(null);
+  return (
+    <>
+      <h1 ref={heading} tabIndex={-1}>
+        Credentials
+      </h1>
+      <Button
+        ref={trigger}
+        onClick={() => {
+          void Promise.resolve(storedDisclosure).then(setDisclosure);
+        }}
+      >
+        Disclose stored secret
+      </Button>
+      <CredentialDisclosureDialog
+        disclosure={disclosure}
+        onClose={() => setDisclosure(null)}
+        resolveReturnFocus={() => trigger.current}
+        fallbackFocus={() => heading.current}
+      />
+    </>
+  );
+}

package/src/forms/CredentialDisclosureDialog/fixtures.ts

@@ -0,0 +1,14 @@
+import type { CredentialDisclosure } from './CredentialDisclosureDialog';
+
+/** Synthetic values only: never use live credentials in previews or tests. */
+export const storedDisclosure: CredentialDisclosure = {
+  variant: 'stored',
+  credentialId: 'cred_demo_01',
+  expiresAt: 'January 1, 2030',
+  secret: 'synthetic_stored_secret_for_demo_only',
+};
+export const freshDisclosure: CredentialDisclosure = {
+  ...storedDisclosure,
+  variant: 'fresh',
+  secret: 'synthetic_fresh_secret_for_demo_only',
+};

package/src/forms/DangerZone/ConfirmDestructiveDialog.tsx

@@ -0,0 +1,101 @@
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  Alert,
+  Button,
+  Field,
+  FieldLabel,
+  Input,
+} from '@gntik-ai/ui';
+import { useState, type ReactNode } from 'react';
+
+export interface ConfirmDestructiveDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: ReactNode;
+  description: ReactNode;
+  /** Text that must be typed exactly to enable the confirming button. */
+  confirmText?: string;
+  confirmLabel: string;
+  /** Runs on confirm; a returned promise shows a loading state and keeps the dialog open until it settles. */
+  onConfirm?: () => void | Promise<void>;
+}
+
+/** Destructive confirmation (alertdialog) that can require typing the resource name first. */
+export function ConfirmDestructiveDialog({
+  open,
+  onOpenChange,
+  title,
+  description,
+  confirmText,
+  confirmLabel,
+  onConfirm,
+}: ConfirmDestructiveDialogProps) {
+  const [typed, setTyped] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const matches = confirmText == null || typed === confirmText;
+
+  const change = (next: boolean) => {
+    if (loading) return;
+    if (!next) {
+      setTyped('');
+      setError(null);
+    }
+    onOpenChange(next);
+  };
+
+  const confirm = async () => {
+    if (!matches) return;
+    setError(null);
+    setLoading(true);
+    try {
+      await onConfirm?.();
+      setLoading(false);
+      setTyped('');
+      onOpenChange(false);
+    } catch (e) {
+      setLoading(false);
+      setError(e instanceof Error ? e.message : 'Something went wrong. Try again.');
+    }
+  };
+
+  return (
+    <AlertDialog open={open} onOpenChange={change}>
+      <AlertDialogContent size="md">
+        <AlertDialogHeader tone="destructive">
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          <AlertDialogDescription>{description}</AlertDialogDescription>
+        </AlertDialogHeader>
+        <form
+          className="mt-5 grid gap-4"
+          onSubmit={(e) => {
+            e.preventDefault();
+            void confirm();
+          }}
+        >
+          {confirmText != null && (
+            <Field>
+              <FieldLabel>
+                Type <span className="font-mono font-semibold text-foreground">{confirmText}</span> to confirm
+              </FieldLabel>
+              <Input value={typed} onValueChange={setTyped} autoComplete="off" spellCheck={false} disabled={loading} />
+            </Field>
+          )}
+          {error && <Alert tone="destructive" description={error} />}
+          <AlertDialogFooter className="mt-1">
+            <AlertDialogCancel disabled={loading}>Cancel</AlertDialogCancel>
+            <Button type="submit" variant="destructive" disabled={!matches} loading={loading}>
+              {confirmLabel}
+            </Button>
+          </AlertDialogFooter>
+        </form>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}

package/src/forms/DangerZone/DangerZone.test.tsx

@@ -0,0 +1,28 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { DangerZone } from './DangerZone';
+
+describe('DangerZone', () => {
+  it('renders the default actions', async () => {
+    const { container } = render(<DangerZone />);
+    expect(screen.getByRole('region', { name: 'Danger zone' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Delete project' })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('requires typing the name before confirming', async () => {
+    const onConfirm = vi.fn();
+    render(<DangerZone onConfirm={onConfirm} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Delete project' }));
+    const dialog = await screen.findByRole('alertdialog');
+    const confirm = screen.getAllByRole('button', { name: 'Delete project' }).at(-1)!;
+    expect(confirm).toBeDisabled();
+    await expectNoAxeViolations(dialog);
+    await userEvent.type(screen.getByLabelText(/to confirm/), 'billing-dashboard');
+    expect(confirm).toBeEnabled();
+    await userEvent.click(confirm);
+    expect(onConfirm).toHaveBeenCalledWith('delete');
+    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());
+  });
+});

package/src/forms/DangerZone/DangerZone.tsx

@@ -0,0 +1,86 @@
+import { Button, cn } from '@gntik-ai/ui';
+import { useId, useState, type ReactNode } from 'react';
+import { ConfirmDestructiveDialog } from './ConfirmDestructiveDialog';
+import { dangerZoneActions, type DangerZoneAction } from './fixtures';
+
+export type { DangerZoneAction } from './fixtures';
+
+export interface DangerZoneProps {
+  title?: ReactNode;
+  description?: ReactNode;
+  actions?: DangerZoneAction[];
+  /** Called after the user confirms an action. A returned promise shows a loading state. */
+  onConfirm?: (actionId: string) => void | Promise<void>;
+  headingLevel?: 'h2' | 'h3' | 'h4';
+  className?: string;
+}
+
+/**
+ * Bordered destructive section. Each action opens a confirmation dialog; actions with
+ * `confirmText` require typing it (e.g. the project name) before the confirm button enables.
+ */
+export function DangerZone({
+  title = 'Danger zone',
+  description = 'These actions affect the whole project and every member who can access it.',
+  actions = dangerZoneActions,
+  onConfirm,
+  headingLevel: Heading = 'h2',
+  className,
+}: DangerZoneProps) {
+  const id = useId();
+  const [pending, setPending] = useState<DangerZoneAction | null>(null);
+  const [open, setOpen] = useState(false);
+
+  return (
+    <section
+      aria-labelledby={`${id}-title`}
+      className={cn('rounded-lg border border-destructive/35 bg-card shadow-sm', className)}
+    >
+      <div className="border-b border-destructive/20 px-6 py-4">
+        <Heading id={`${id}-title`} className="text-[15px] font-semibold tracking-tight text-destructive-text">
+          {title}
+        </Heading>
+        {description != null && (
+          <p className="mt-1 text-[13px] leading-6 text-pretty text-muted-foreground">{description}</p>
+        )}
+      </div>
+      <ul className="divide-y divide-border">
+        {actions.map((action) => (
+          <li
+            key={action.id}
+            className="flex flex-col gap-3 px-6 py-4 sm:flex-row sm:items-center sm:justify-between sm:gap-6"
+          >
+            <div className="min-w-0">
+              <div className="text-[13.5px] font-semibold text-foreground">{action.title}</div>
+              <p className="mt-0.5 max-w-xl text-[12.5px] leading-5 text-pretty text-muted-foreground">
+                {action.description}
+              </p>
+            </div>
+            <Button
+              variant={action.destructive === false ? 'secondary' : 'destructive'}
+              className="shrink-0 self-start sm:self-auto"
+              onClick={() => {
+                setPending(action);
+                setOpen(true);
+              }}
+            >
+              {action.actionLabel}
+            </Button>
+          </li>
+        ))}
+      </ul>
+      {pending && (
+        <ConfirmDestructiveDialog
+          key={pending.id}
+          open={open}
+          onOpenChange={setOpen}
+          title={`${pending.title}?`}
+          description={pending.description}
+          confirmText={pending.confirmText}
+          confirmLabel={pending.actionLabel}
+          onConfirm={() => onConfirm?.(pending.id)}
+        />
+      )}
+    </section>
+  );
+}

package/src/forms/DangerZone/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Danger zone',
+  family: 'forms',
+  status: 'stable',
+  description:
+    'Bordered destructive section whose actions open an alert dialog that can require typing the resource name.',
+  uses: ['Button', 'AlertDialog', 'Field', 'Input', 'Alert'],
+};

package/src/forms/DangerZone/fixtures.ts

@@ -0,0 +1,36 @@
+export interface DangerZoneAction {
+  id: string;
+  title: string;
+  description: string;
+  /** Label of the row button and of the confirming button. */
+  actionLabel: string;
+  /** Text the user must type to confirm (e.g. the resource name). Omit for a plain confirmation. */
+  confirmText?: string;
+  /** Use the destructive button style in the row (default true); `false` renders a secondary button. */
+  destructive?: boolean;
+}
+
+export const dangerZoneActions: DangerZoneAction[] = [
+  {
+    id: 'transfer',
+    title: 'Transfer project',
+    description: 'Move this project and its deployments to another workspace you administer.',
+    actionLabel: 'Transfer',
+    destructive: false,
+  },
+  {
+    id: 'archive',
+    title: 'Archive project',
+    description: 'Stops every deployment and makes the project read-only. You can restore it later.',
+    actionLabel: 'Archive',
+    confirmText: 'billing-dashboard',
+  },
+  {
+    id: 'delete',
+    title: 'Delete project',
+    description:
+      'Permanently deletes billing-dashboard, its deployments, secrets and audit log. This cannot be undone.',
+    actionLabel: 'Delete project',
+    confirmText: 'billing-dashboard',
+  },
+];

package/src/forms/DateRangeFilter/DateRangeFilter.test.tsx

@@ -0,0 +1,26 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { DateRangeFilter } from './DateRangeFilter';
+
+const today = new Date(2026, 5, 15);
+
+describe('DateRangeFilter', () => {
+  it('renders the last 7 days by default', async () => {
+    const { container } = render(<DateRangeFilter today={today} />);
+    const field = screen.getByRole('combobox', { name: 'Date range' });
+    expect((field as HTMLInputElement).value).toMatch(/Jun 9/);
+    await expectNoAxeViolations(container);
+  });
+
+  it('applies a preset and clears', async () => {
+    const onValueChange = vi.fn();
+    render(<DateRangeFilter today={today} onValueChange={onValueChange} />);
+    await userEvent.click(screen.getByRole('combobox', { name: 'Date range' }));
+    await userEvent.click(await screen.findByRole('button', { name: 'Today' }));
+    expect(onValueChange).toHaveBeenLastCalledWith({ start: today, end: today });
+    await userEvent.click(screen.getByRole('button', { name: 'Clear date range' }));
+    expect(onValueChange).toHaveBeenLastCalledWith({ start: null, end: null });
+    expect(screen.getByRole('combobox', { name: 'Date range' })).toHaveValue('');
+  });
+});

package/src/forms/DateRangeFilter/DateRangeFilter.tsx

@@ -0,0 +1,83 @@
+import {
+  DEFAULT_DATE_RANGE_PRESETS,
+  DateRangePicker,
+  IconButton,
+  cn,
+  type DateRange,
+  type DateRangePreset,
+  useI18n,
+} from '@gntik-ai/ui';
+import { X } from '@gntik-ai/icons';
+import { useState } from 'react';
+
+export interface DateRangeFilterProps {
+  value?: DateRange;
+  /** Initial range; defaults to the "Last 7 days" preset. Pass `{ start: null, end: null }` for none. */
+  defaultValue?: DateRange;
+  /** Called with a complete range, or an empty one when cleared. */
+  onValueChange?: (range: DateRange) => void;
+  presets?: DateRangePreset[];
+  /** "Today" for the presets (defaults to the current date). */
+  today?: Date;
+  /** Accessible name of the field. */
+  label?: string;
+  placeholder?: string;
+  /** Show a clear button while a range is set. */
+  clearable?: boolean;
+  disabled?: boolean;
+  className?: string;
+}
+
+const EMPTY: DateRange = { start: null, end: null };
+const SHORT: Intl.DateTimeFormatOptions = { month: 'short', day: 'numeric' };
+
+/** Compact DateRangePicker for toolbars: small trigger, short dates, presets and a clear button. */
+export function DateRangeFilter({
+  value,
+  defaultValue,
+  onValueChange,
+  presets = DEFAULT_DATE_RANGE_PRESETS,
+  today,
+  label: labelProp,
+  placeholder: placeholderProp,
+  clearable = true,
+  disabled,
+  className,
+}: DateRangeFilterProps) {
+  const { t } = useI18n();
+  const label = labelProp ?? t('dateRange.label');
+  const placeholder = placeholderProp ?? t('dateRange.any');
+  const [inner, setInner] = useState<DateRange>(
+    () => defaultValue ?? presets.find((p) => p.id === 'last-7')?.range?.(today ?? new Date()) ?? EMPTY,
+  );
+  const range = value ?? inner;
+  const set = (next: DateRange) => {
+    setInner(next);
+    onValueChange?.(next);
+  };
+  return (
+    <div className={cn('inline-flex items-center gap-1', className)}>
+      <DateRangePicker
+        size="sm"
+        aria-label={label}
+        value={range}
+        onValueChange={set}
+        presets={presets}
+        today={today}
+        placeholder={placeholder}
+        formatOptions={SHORT}
+        disabled={disabled}
+        className="w-[13.5rem]"
+      />
+      {clearable && range.start && (
+        <IconButton
+          icon={X}
+          size="sm"
+          label={t('common.clearItem', { label: label.toLowerCase() })}
+          disabled={disabled}
+          onClick={() => set(EMPTY)}
+        />
+      )}
+    </div>
+  );
+}

package/src/forms/DateRangeFilter/block.meta.ts

@@ -0,0 +1,9 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Date range filter',
+  family: 'forms',
+  status: 'stable',
+  description: 'Compact date range picker for toolbars: small trigger with short dates, presets and a clear button.',
+  uses: ['DateRangePicker', 'IconButton'],
+};

package/src/forms/DialogWizard/DialogWizard.test.tsx

@@ -0,0 +1,95 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { DescriptionListCard } from '../../data-display/DescriptionListCard/DescriptionListCard';
+import { ValidationSummary } from '../ValidationSummary/ValidationSummary';
+import { DialogWizard } from './DialogWizard';
+import { expectNoAxeViolations } from '../../test/a11y';
+
+describe('DialogWizard', () => {
+  it('uses consumer labels and shows validation and review slots with the shared step footer', async () => {
+    const user = userEvent.setup();
+    const props = {
+      open: true,
+      title: 'Provision database',
+      description: 'Configure storage',
+      steps: [{ label: 'Engine' }, { label: 'Check answers' }],
+      cancelLabel: 'Abandon',
+      backLabel: 'Previous',
+      nextLabel: 'Continue',
+      finishLabel: 'Provision',
+      exitLabel: 'Close flow',
+      stepsLabel: 'Stages',
+      stepsSummaryLabel: 'Stage count',
+      pendingLabel: 'Provisioning',
+      stepAnnouncement: ({ position }: { position: number }) => `Stage ${position}`,
+    };
+    const { rerender } = render(
+      <DialogWizard
+        {...props}
+        current={0}
+        nextDisabled
+        stepError={
+          <ValidationSummary title="Fix the engine" errors={[{ fieldId: 'engine', message: 'Choose an engine' }]} />
+        }
+      >
+        <input id="engine" aria-label="Engine choice" />
+      </DialogWizard>,
+    );
+    expect(await screen.findByRole('dialog', { name: 'Provision database' })).toHaveAccessibleDescription(
+      'Configure storage',
+    );
+    expect(screen.getByRole('button', { name: 'Continue' })).toBeDisabled();
+    expect(screen.getByText('Fix the engine')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Abandon' })).toBeInTheDocument();
+    await user.click(screen.getByRole('link', { name: 'Choose an engine' }));
+    expect(screen.getByRole('textbox')).toHaveFocus();
+    const onFinish = vi.fn();
+    rerender(
+      <DialogWizard
+        {...props}
+        current={1}
+        onFinish={onFinish}
+        reviewStep={
+          <DescriptionListCard
+            title="Your answers"
+            description="Review storage"
+            items={[{ id: 'engine', label: 'Engine', value: 'Standard' }]}
+          />
+        }
+      />,
+    );
+    expect(screen.getByText('Your answers')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Previous' })).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Provision' }));
+    expect(onFinish).toHaveBeenCalledTimes(1);
+  });
+
+  for (const theme of ['dark', 'light', 'high_contrast']) {
+    for (const size of ['dialog', 'fullscreen'] as const) {
+      it.each([1, 2])(`has no axe violations in ${theme}, ${size}, step %s`, async (current) => {
+        document.documentElement.className = theme === 'light' ? '' : theme;
+        render(
+          <DialogWizard
+            open
+            title="Create resource"
+            description="Configure storage"
+            size={size}
+            steps={[{ label: 'Details' }, { label: 'Configuration' }, { label: 'Review' }]}
+            current={current}
+            reviewStep={
+              <DescriptionListCard
+                title="Answers"
+                description="Review your choices"
+                items={[{ id: 'name', label: 'Name', value: 'Resource' }]}
+              />
+            }
+          >
+            <h2>Configuration</h2>
+            <input aria-label="Region" />
+          </DialogWizard>,
+        );
+        await expectNoAxeViolations(await screen.findByRole('dialog'));
+      });
+    }
+  }
+});

package/src/forms/DialogWizard/DialogWizard.tsx

@@ -0,0 +1,39 @@
+import { useI18n, WizardLayout, type WizardLayoutProps } from '@gntik-ai/ui';
+import type { ReactNode } from 'react';
+
+export interface DialogWizardProps extends Omit<WizardLayoutProps, 'mode' | 'steps' | 'current'> {
+  steps?: WizardLayoutProps['steps'];
+  current?: number;
+  /** Step-local validation surface, normally a ValidationSummary with consumer copy. */
+  stepError?: ReactNode;
+  /** Replaces the last step body, normally a DescriptionListCard with consumer copy. */
+  reviewStep?: ReactNode;
+}
+
+/** Modal variant of create-wizard for a flow over its parent page. State stays consumer-owned. */
+export function DialogWizard({
+  steps,
+  current = 0,
+  size = 'dialog',
+  stepError,
+  reviewStep,
+  children,
+  title,
+  ...props
+}: DialogWizardProps) {
+  const { t } = useI18n();
+  const items = steps ?? [{ label: t('wizard.details') }, { label: t('wizard.review') }];
+  return (
+    <WizardLayout
+      {...props}
+      mode="overlay"
+      size={size}
+      steps={items}
+      current={current}
+      title={title ?? t('wizard.title')}
+    >
+      {stepError}
+      {current >= items.length - 1 && reviewStep != null ? reviewStep : children}
+    </WizardLayout>
+  );
+}

package/src/forms/DialogWizard/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Dialog wizard',
+  family: 'forms',
+  status: 'beta',
+  description:
+    'Modal variant of create-wizard for create flows over their parent page, without a route change. Defaults to dialog size (fullscreen on mobile); size="fullscreen" fills every viewport. Consumer-controlled step state survives closing. Use the create-wizard page template for a dedicated page flow, or WizardLayout mode="overlay" for a fullscreen flow. Supply all labels, pendingLabel and stepAnnouncement from your own i18n; stepError accepts ValidationSummary and reviewStep accepts DescriptionListCard.',
+  uses: ['WizardLayout', 'Dialog', 'Stepper', 'Button'],
+};