@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/feedback/ConfirmDestructive/ConfirmDestructive.tsx

@@ -0,0 +1,145 @@
+import { Trash2 } from '@gntik-ai/icons';
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+  Button,
+  Field,
+  FieldLabel,
+  Input,
+} from '@gntik-ai/ui';
+import { useState, type FormEvent, type ReactNode } from 'react';
+
+export interface ConfirmDestructiveProps {
+  /** Exact name the user must type to unlock the action. */
+  resourceName?: string;
+  /** What kind of resource it is (used in the default copy). */
+  resourceType?: string;
+  title?: ReactNode;
+  description?: ReactNode;
+  /** What will be lost, as a short list. */
+  consequences?: string[];
+  /** Label of the confirming button (and of the default trigger). */
+  confirmLabel?: string;
+  /** Default trigger button text; `null` renders no trigger (control `open` instead). */
+  triggerLabel?: string | null;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Runs on confirm. Returning a promise keeps the dialog open with a spinner until it settles; a rejection shows its message. */
+  onConfirm?: () => void | Promise<void>;
+}
+
+/**
+ * Typed-confirmation for irreversible actions: an AlertDialog whose destructive button stays
+ * disabled until the resource name is typed exactly.
+ */
+export function ConfirmDestructive({
+  resourceName = 'acme-web',
+  resourceType = 'project',
+  title,
+  description,
+  consequences = [
+    'All deployments and preview URLs',
+    'Environment variables and secrets',
+    'The audit log for this project',
+  ],
+  confirmLabel,
+  triggerLabel,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  onConfirm,
+}: ConfirmDestructiveProps) {
+  const [innerOpen, setInnerOpen] = useState(defaultOpen);
+  const [typed, setTyped] = useState('');
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const isOpen = open ?? innerOpen;
+  const label = confirmLabel ?? `Delete ${resourceType}`;
+  const matches = typed === resourceName;
+
+  const setOpen = (next: boolean) => {
+    if (!next) {
+      setTyped('');
+      setError(null);
+    }
+    setInnerOpen(next);
+    onOpenChange?.(next);
+  };
+
+  const confirm = async (event: FormEvent) => {
+    event.preventDefault();
+    if (!matches || pending) return;
+    setPending(true);
+    setError(null);
+    try {
+      await onConfirm?.();
+      setPending(false);
+      setOpen(false);
+    } catch (err) {
+      setPending(false);
+      setError(err instanceof Error ? err.message : 'Something went wrong. Try again.');
+    }
+  };
+
+  return (
+    <AlertDialog open={isOpen} onOpenChange={(next) => !pending && setOpen(next)}>
+      {triggerLabel !== null && (
+        <AlertDialogTrigger render={<Button variant="destructive" icon={Trash2} />}>
+          {triggerLabel ?? label}
+        </AlertDialogTrigger>
+      )}
+      <AlertDialogContent>
+        <AlertDialogHeader tone="destructive">
+          <AlertDialogTitle>{title ?? `Delete ${resourceType}?`}</AlertDialogTitle>
+          <AlertDialogDescription>
+            {description ?? (
+              <>
+                This permanently deletes <span className="font-mono text-foreground">{resourceName}</span>. This action
+                cannot be undone.
+              </>
+            )}
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        {consequences.length > 0 && (
+          <ul className="mt-4 list-disc space-y-1 rounded-md border border-destructive/25 bg-destructive/5 py-2.5 pe-3 ps-8 text-[12.5px] text-muted-foreground">
+            {consequences.map((c) => (
+              <li key={c}>{c}</li>
+            ))}
+          </ul>
+        )}
+        <form onSubmit={(e) => void confirm(e)} className="mt-4">
+          <Field>
+            <FieldLabel>
+              Type <span className="font-mono font-semibold text-foreground">{resourceName}</span> to confirm
+            </FieldLabel>
+            <Input
+              value={typed}
+              onChange={(e) => setTyped(e.target.value)}
+              autoComplete="off"
+              spellCheck={false}
+              disabled={pending}
+            />
+          </Field>
+          {error && (
+            <p role="alert" className="mt-2 text-[12.5px] text-destructive-text">
+              {error}
+            </p>
+          )}
+          <AlertDialogFooter className="mt-5">
+            <AlertDialogCancel disabled={pending}>Cancel</AlertDialogCancel>
+            <Button type="submit" variant="destructive" loading={pending} disabled={!matches}>
+              {label}
+            </Button>
+          </AlertDialogFooter>
+        </form>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}

package/src/feedback/ConfirmDestructive/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Confirm destructive',
+  family: 'feedback',
+  status: 'beta',
+  description:
+    'AlertDialog for irreversible actions that requires typing the resource name, with async confirm and error display.',
+  uses: ['AlertDialog', 'Button', 'Field', 'Input'],
+};

package/src/feedback/EmptyStates/EmptyStates.test.tsx

@@ -0,0 +1,48 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { FirstRunEmpty, NoAccessEmpty, NoResultsEmpty } from './EmptyStates';
+
+describe('EmptyStates', () => {
+  it('renders the three defaults', async () => {
+    const { container } = render(
+      <>
+        <FirstRunEmpty />
+        <NoResultsEmpty />
+        <NoAccessEmpty />
+      </>,
+    );
+    expect(screen.getByRole('heading', { name: 'Create your first project' })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: /No projects match/ })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: 'You don’t have access to Billing' })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('wires the first-run and no-results actions', async () => {
+    const user = userEvent.setup();
+    const onAction = vi.fn();
+    const onClearFilters = vi.fn();
+    const onClearSearch = vi.fn();
+    render(
+      <>
+        <FirstRunEmpty onAction={onAction} />
+        <NoResultsEmpty onClearFilters={onClearFilters} onClearSearch={onClearSearch} />
+      </>,
+    );
+    await user.click(screen.getByRole('button', { name: 'New project' }));
+    await user.click(screen.getByRole('button', { name: 'Clear filters' }));
+    await user.click(screen.getByRole('button', { name: 'Clear search' }));
+    expect(onAction).toHaveBeenCalledTimes(1);
+    expect(onClearFilters).toHaveBeenCalledTimes(1);
+    expect(onClearSearch).toHaveBeenCalledTimes(1);
+  });
+
+  it('requests access once', async () => {
+    const onRequestAccess = vi.fn(() => Promise.resolve());
+    render(<NoAccessEmpty onRequestAccess={onRequestAccess} />);
+    await userEvent.setup().click(screen.getByRole('button', { name: 'Request access' }));
+    expect(onRequestAccess).toHaveBeenCalledTimes(1);
+    expect(await screen.findByRole('button', { name: 'Access requested' })).toBeDisabled();
+    expect(screen.getByRole('status')).toHaveTextContent('Access request sent');
+  });
+});

package/src/feedback/EmptyStates/EmptyStates.tsx

@@ -0,0 +1,191 @@
+import { Check, FolderPlus, Lock, SearchX } from '@gntik-ai/icons';
+import type { LucideIcon } from '@gntik-ai/icons';
+import { Button, EmptyState, Link, cn } from '@gntik-ai/ui';
+import { useState, type ReactNode } from 'react';
+import { firstRunSteps, noAccessSample, noResultsSample } from './fixtures';
+
+interface SharedEmptyProps {
+  /** Heading level that fits the page outline. */
+  titleAs?: 'h2' | 'h3' | 'h4';
+  /** Dashed border around the state (use inside a card or table). */
+  bordered?: boolean;
+  className?: string;
+}
+
+export interface FirstRunEmptyProps extends SharedEmptyProps {
+  icon?: LucideIcon;
+  title?: ReactNode;
+  description?: ReactNode;
+  actionLabel?: string;
+  onAction?: () => void;
+  /** Secondary link (docs, guide). `null` hides it. */
+  secondary?: { label: string; href: string } | null;
+  /** Short checklist of what the first run involves. */
+  steps?: string[];
+}
+
+/** First-run state: nothing created yet; explains the value and offers the first action. */
+export function FirstRunEmpty({
+  icon = FolderPlus,
+  title = 'Create your first project',
+  description = 'Projects group your services, environments and deployments. Start one from a repository in a couple of minutes.',
+  actionLabel = 'New project',
+  onAction,
+  secondary = { label: 'Read the guide', href: '#guide' },
+  steps = firstRunSteps,
+  titleAs,
+  bordered = true,
+  className,
+}: FirstRunEmptyProps) {
+  return (
+    <EmptyState
+      icon={icon}
+      title={title}
+      titleAs={titleAs}
+      description={description}
+      bordered={bordered}
+      className={cn('mx-auto', className)}
+      primaryAction={<Button onClick={onAction}>{actionLabel}</Button>}
+      secondaryAction={
+        secondary ? (
+          <Link
+            underline="hover"
+            href={secondary.href}
+            className="inline-flex h-9 items-center px-2 text-[13px] font-semibold"
+          >
+            {secondary.label}
+          </Link>
+        ) : undefined
+      }
+    >
+      {steps.length > 0 && (
+        <ol className="mt-6 grid gap-2 text-start text-[12.5px] text-muted-foreground">
+          {steps.map((step, i) => (
+            <li key={step} className="flex items-center gap-2.5">
+              <span className="grid size-5 shrink-0 place-items-center rounded-full bg-primary/14 font-mono text-[10.5px] font-semibold text-primary-chip-text">
+                {i + 1}
+              </span>
+              {step}
+            </li>
+          ))}
+        </ol>
+      )}
+    </EmptyState>
+  );
+}
+
+export interface NoResultsEmptyProps extends SharedEmptyProps {
+  /** The search text that matched nothing. */
+  query?: string;
+  /** Number of active filters (shows "Clear filters" when > 0). */
+  filterCount?: number;
+  /** Plural noun for what is being searched. */
+  entity?: string;
+  onClearFilters?: () => void;
+  onClearSearch?: () => void;
+}
+
+/** No-results state for a filtered list or table: echoes the query and offers ways out. */
+export function NoResultsEmpty({
+  query = noResultsSample.query,
+  filterCount = noResultsSample.filterCount,
+  entity = noResultsSample.entity,
+  onClearFilters,
+  onClearSearch,
+  titleAs,
+  bordered = false,
+  className,
+}: NoResultsEmptyProps) {
+  const filters = filterCount > 0 ? ` with ${filterCount} ${filterCount === 1 ? 'filter' : 'filters'} applied` : '';
+  return (
+    <EmptyState
+      icon={SearchX}
+      size="sm"
+      titleAs={titleAs}
+      bordered={bordered}
+      className={cn('mx-auto', className)}
+      title={
+        query ? (
+          <>
+            No {entity} match “<span className="font-mono">{query}</span>”
+          </>
+        ) : (
+          `No ${entity} found`
+        )
+      }
+      description={`Check the spelling or try a broader search${filters}.`}
+      primaryAction={
+        filterCount > 0 ? (
+          <Button variant="secondary" size="sm" onClick={onClearFilters}>
+            Clear filters
+          </Button>
+        ) : undefined
+      }
+      secondaryAction={
+        query ? (
+          <Button variant="ghost" size="sm" onClick={onClearSearch}>
+            Clear search
+          </Button>
+        ) : undefined
+      }
+    />
+  );
+}
+
+export interface NoAccessEmptyProps extends SharedEmptyProps {
+  /** What the viewer cannot see. */
+  resource?: string;
+  /** Who can grant access. */
+  owner?: string;
+  /** Called on "Request access"; may return a promise (the button shows a spinner). */
+  onRequestAccess?: () => void | Promise<void>;
+  /** Start in the "requested" state (e.g. a pending request exists). */
+  defaultRequested?: boolean;
+}
+
+/** Permission state: the viewer lacks access; explains who can grant it and lets them ask. */
+export function NoAccessEmpty({
+  resource = noAccessSample.resource,
+  owner = noAccessSample.owner,
+  onRequestAccess,
+  defaultRequested = false,
+  titleAs,
+  bordered = true,
+  className,
+}: NoAccessEmptyProps) {
+  const [state, setState] = useState<'idle' | 'pending' | 'requested'>(defaultRequested ? 'requested' : 'idle');
+  const request = async () => {
+    setState('pending');
+    try {
+      await onRequestAccess?.();
+      setState('requested');
+    } catch {
+      setState('idle');
+    }
+  };
+  return (
+    <EmptyState
+      icon={Lock}
+      titleAs={titleAs}
+      bordered={bordered}
+      className={cn('mx-auto', className)}
+      title={`You don’t have access to ${resource}`}
+      description={`Ask ${owner} to grant you a role that includes ${resource.toLowerCase()} permissions.`}
+      primaryAction={
+        <Button
+          variant={state === 'requested' ? 'secondary' : 'primary'}
+          icon={state === 'requested' ? Check : undefined}
+          loading={state === 'pending'}
+          disabled={state === 'requested'}
+          onClick={() => void request()}
+        >
+          {state === 'requested' ? 'Access requested' : 'Request access'}
+        </Button>
+      }
+    >
+      <p role="status" className="sr-only">
+        {state === 'requested' ? 'Access request sent' : ''}
+      </p>
+    </EmptyState>
+  );
+}

package/src/feedback/EmptyStates/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Empty states',
+  family: 'feedback',
+  status: 'beta',
+  description:
+    'Three canonical empty states: first run (with checklist), no results (clear filters/search) and no access (request access).',
+  uses: ['EmptyState', 'Button', 'Link'],
+};

package/src/feedback/EmptyStates/fixtures.ts

@@ -0,0 +1,6 @@
+/** Neutral sample copy for the empty states. */
+export const firstRunSteps = ['Connect a Git repository', 'Configure build settings', 'Deploy to an environment'];
+
+export const noResultsSample = { query: 'billing-api', filterCount: 2, entity: 'projects' } as const;
+
+export const noAccessSample = { resource: 'Billing', owner: 'an organization admin' } as const;

package/src/feedback/ErrorPanel/ErrorPanel.test.tsx

@@ -0,0 +1,37 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { ErrorPanel } from './ErrorPanel';
+
+describe('ErrorPanel', () => {
+  it('accepts a null code to hide the fixture chip', () => {
+    render(<ErrorPanel code={null} />);
+    expect(screen.queryByText('503')).not.toBeInTheDocument();
+  });
+
+  it('renders the default panel', async () => {
+    const { container } = render(<ErrorPanel onRetry={() => {}} />);
+    expect(screen.getByRole('region', { name: 'We couldn’t load deployments' })).toBeInTheDocument();
+    expect(screen.getByText('req_8f2c41d07a9b')).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('shows a loading state while retrying and reveals details', async () => {
+    const user = userEvent.setup();
+    let resolve = () => {};
+    const onRetry = vi.fn(() => new Promise<void>((r) => (resolve = r)));
+    render(<ErrorPanel onRetry={onRetry} />);
+    await user.click(screen.getByRole('button', { name: 'Try again' }));
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    const busy = screen.getByRole('button', { name: 'Retrying…' });
+    expect(busy).toHaveAttribute('aria-busy', 'true');
+    resolve();
+    expect(await screen.findByRole('button', { name: 'Try again' })).toBeEnabled();
+
+    const toggle = screen.getByRole('button', { name: 'Technical details' });
+    expect(toggle).toHaveAttribute('aria-expanded', 'false');
+    await user.click(toggle);
+    expect(toggle).toHaveAttribute('aria-expanded', 'true');
+    expect(screen.getByText(/503 Service Unavailable/)).toBeVisible();
+  });
+});

package/src/feedback/ErrorPanel/ErrorPanel.tsx

@@ -0,0 +1,146 @@
+import { Check, Copy, RotateCw, ServerCrash } from '@gntik-ai/icons';
+import type { LucideIcon } from '@gntik-ai/icons';
+import { Button, Collapsible, CollapsiblePanel, CollapsibleTrigger, IconButton, cn, useI18n } from '@gntik-ai/ui';
+import { useId, useRef, useState, type ReactNode } from 'react';
+import type { FeedbackAction } from '../types';
+
+export interface ErrorPanelProps {
+  icon?: LucideIcon;
+  title?: ReactNode;
+  /** Human summary of what failed and what to do. */
+  message?: ReactNode;
+  /** Status or error code shown as a mono chip (e.g. 503, ECONNRESET). */
+  code?: string | number | null;
+  /** Correlation id for support; gets a copy button. */
+  requestId?: string;
+  /** Raw details (response body, stack) behind a disclosure. */
+  details?: string;
+  /** Retry handler. A returned promise shows the loading state until it settles. */
+  onRetry?: () => void | Promise<void>;
+  /** Force the loading state from outside. */
+  retrying?: boolean;
+  retryLabel?: string;
+  /** Extra action next to Retry (e.g. contact support). */
+  secondaryAction?: FeedbackAction | null;
+  titleAs?: 'h2' | 'h3';
+  className?: string;
+}
+
+/** Error summary for a failed load or action: what happened, request id, retry and technical details. */
+export function ErrorPanel({
+  icon: Icon = ServerCrash,
+  title = 'We couldn’t load deployments',
+  message = 'The service didn’t respond in time. Your data is safe; try again in a moment.',
+  code = 503,
+  requestId = 'req_8f2c41d07a9b',
+  details = 'GET /v1/projects/acme-web/deployments\n503 Service Unavailable\nupstream timed out after 30000 ms (pool: api-eu-west-1)',
+  onRetry,
+  retrying,
+  retryLabel: retryLabelProp,
+  secondaryAction = { label: 'Contact support', variant: 'ghost' },
+  titleAs: Heading = 'h3',
+  className,
+}: ErrorPanelProps) {
+  const { t } = useI18n();
+  const retryLabel = retryLabelProp ?? t('error.retry');
+  const id = useId();
+  const [innerRetrying, setInnerRetrying] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const copyTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const busy = retrying ?? innerRetrying;
+
+  const retry = async () => {
+    if (!onRetry || busy) return;
+    setInnerRetrying(true);
+    try {
+      await onRetry();
+    } finally {
+      setInnerRetrying(false);
+    }
+  };
+
+  const copy = async () => {
+    if (!requestId) return;
+    try {
+      await navigator.clipboard.writeText(requestId);
+      setCopied(true);
+      clearTimeout(copyTimer.current);
+      copyTimer.current = setTimeout(() => setCopied(false), 2000);
+    } catch {
+      setCopied(false);
+    }
+  };
+
+  return (
+    <section
+      aria-labelledby={`${id}-title`}
+      className={cn('rounded-lg border border-destructive/30 bg-card p-5 shadow-sm', className)}
+    >
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-start">
+        <span className="grid size-10 shrink-0 place-items-center rounded-lg bg-destructive/10 text-destructive-chip-text">
+          <Icon size={20} aria-hidden />
+        </span>
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-center gap-2">
+            <Heading id={`${id}-title`} className="text-[15px] font-semibold tracking-tight text-foreground">
+              {title}
+            </Heading>
+            {code != null && (
+              <span className="rounded bg-destructive/10 px-1.5 py-0.5 font-mono text-[11px] font-semibold text-destructive-chip-text">
+                {code}
+              </span>
+            )}
+          </div>
+          {message != null && <p className="mt-1.5 max-w-xl text-[13px] leading-6 text-muted-foreground">{message}</p>}
+          {requestId && (
+            <div className="mt-3 flex items-center gap-1.5 text-[12px] text-muted-foreground">
+              <span>{t('error.requestId')}</span>
+              <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-[11.5px] text-foreground">
+                {requestId}
+              </code>
+              <IconButton
+                icon={copied ? Check : Copy}
+                label={copied ? t('common.copied') : t('error.copyRequestId')}
+                size="sm"
+                variant="ghost"
+                className="size-7"
+                onClick={() => void copy()}
+              />
+            </div>
+          )}
+          <div className="mt-4 flex flex-wrap items-center gap-2">
+            {onRetry && (
+              <Button variant="secondary" size="sm" icon={RotateCw} loading={busy} onClick={() => void retry()}>
+                {busy ? t('error.retrying') : retryLabel}
+              </Button>
+            )}
+            {secondaryAction && (
+              <Button
+                size="sm"
+                variant={secondaryAction.variant ?? 'ghost'}
+                icon={secondaryAction.icon}
+                disabled={secondaryAction.disabled}
+                onClick={secondaryAction.onClick}
+              >
+                {secondaryAction.label}
+              </Button>
+            )}
+          </div>
+          {details && (
+            <Collapsible className="mt-4">
+              <CollapsibleTrigger className="text-[12.5px]">{t('error.details')}</CollapsibleTrigger>
+              <CollapsiblePanel>
+                <pre className="mt-2 max-h-60 overflow-auto rounded-md border border-border bg-muted/50 p-3 font-mono text-[11.5px] leading-5 whitespace-pre-wrap text-foreground">
+                  {details}
+                </pre>
+              </CollapsiblePanel>
+            </Collapsible>
+          )}
+          <p role="status" className="sr-only">
+            {busy ? t('error.retryingStatus') : copied ? t('error.requestIdCopied') : ''}
+          </p>
+        </div>
+      </div>
+    </section>
+  );
+}

package/src/feedback/ErrorPanel/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Error panel',
+  family: 'feedback',
+  status: 'beta',
+  description:
+    'Error summary with status code, copyable request id, retry with loading state and a technical-details disclosure.',
+  uses: ['Button', 'IconButton', 'Collapsible'],
+};

package/src/feedback/InlineCallout/InlineCallout.test.tsx

@@ -0,0 +1,33 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { InlineCallout } from './InlineCallout';
+
+describe('InlineCallout', () => {
+  it('renders the default callout', async () => {
+    const { container } = render(<InlineCallout />);
+    expect(screen.getByRole('status', { name: /92% of your build minutes/ })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'View usage' })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('runs actions and dismisses', async () => {
+    const user = userEvent.setup();
+    const onRetry = vi.fn();
+    const onDismiss = vi.fn();
+    render(
+      <InlineCallout
+        tone="destructive"
+        title="Sync failed"
+        actions={[{ label: 'Retry', onClick: onRetry }]}
+        dismissible
+        onDismiss={onDismiss}
+      />,
+    );
+    await user.click(screen.getByRole('button', { name: 'Retry' }));
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    await user.click(screen.getByRole('button', { name: 'Dismiss' }));
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+  });
+});