@mindlogic-ai/logician-ui 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/components/Button/Button.stories.tsx

@@ -1,8 +1,12 @@
+import { type ReactNode, useId, useRef, useState } from 'react';
 import { Box, Flex, Grid, HStack, Text, VStack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Card } from '../Card';
 import { Sparkles, TrashIcon } from '../Icon';
-import { Button, buttonVariants } from '.';
+import { Button, buttonVariants, buttonVariantStyles } from '.';
 import { ButtonVariant } from './Button.types';
 
 const meta = {
@@ -12,11 +16,13 @@ const meta = {
     variant: {
       control: 'select',
       options: buttonVariants,
-      description: 'Role (fill, border and text together). Default `subtle`.',
+      description:
+        'Role (fill, border and text together). `primary`: the one main action of a screen. `action`: run — black fill, coral icon. `accent`: the coloured CTA of a landing page or hero, one per view. `secondary`: an alternative or a way out. `subtle` (default): low emphasis with a shape. `ghost`: toolbars and inline actions. `danger`: confirms a destructive step.',
     },
     isDestructive: {
       control: 'boolean',
-      description: 'Danger text on secondary / ghost / subtle',
+      description:
+        'Danger-coloured label (`danger.fg`) on `secondary` / `subtle` / `ghost` for a destructive action that does not deserve a red fill. Ignored on filled roles.',
     },
   },
 } satisfies Meta<typeof Button>;
@@ -257,3 +263,326 @@ export const AsLink: Story = {
     </Flex>
   ),
 };
+
+/**
+ * `focusableWhenDisabled` keeps a disabled button reachable so it can explain
+ * itself. Tab to 결제 with the box unticked, then press it: `onClick` does not
+ * run, `onDisabledClick` moves focus to the box and the hint turns red.
+ *
+ * It is disabled by `aria-disabled="true"` instead of the native attribute, so
+ * it looks the same as the native disabled button next to it, ignores hover
+ * and press, and does not submit a form.
+ */
+export const FocusableWhenDisabled: Story = {
+  render: function Render() {
+    const [agreed, setAgreed] = useState(false);
+    const [nudged, setNudged] = useState(false);
+    const [paid, setPaid] = useState(0);
+    const checkboxRef = useRef<HTMLInputElement>(null);
+    const hintId = useId();
+    return (
+      <VStack align="flex-start" gap={3} p={4} maxW="360px">
+        <label style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+          <input
+            ref={checkboxRef}
+            type="checkbox"
+            checked={agreed}
+            onChange={(event) => {
+              setAgreed(event.target.checked);
+              setNudged(false);
+            }}
+          />
+          <Text fontSize="sm">이용 및 환불 안내에 동의합니다</Text>
+        </label>
+        {!agreed && (
+          <Text
+            id={hintId}
+            fontSize="sm"
+            color={nudged ? 'danger.fg' : 'fg.muted'}
+          >
+            안내에 동의하면 결제할 수 있습니다.
+          </Text>
+        )}
+        <HStack gap={3}>
+          <Button
+            variant="primary"
+            disabled={!agreed}
+            focusableWhenDisabled
+            aria-describedby={agreed ? undefined : hintId}
+            onDisabledClick={() => {
+              setNudged(true);
+              checkboxRef.current?.focus();
+            }}
+            onClick={() => setPaid((n) => n + 1)}
+          >
+            결제
+          </Button>
+          <Button variant="primary" disabled>
+            native disabled
+          </Button>
+        </HStack>
+        <Text fontSize="sm" color="fg.muted">
+          onClick: {paid}
+        </Text>
+      </VStack>
+    );
+  },
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Button.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); being stories, they type-check with the rest of the code.
+// `tags` is written out on each story: the indexer reads CSF statically.
+
+/** A dialog-like panel: title, one line of body, a right-aligned footer. */
+const Panel = ({
+  title,
+  body,
+  children,
+}: {
+  title: string;
+  body: string;
+  children: ReactNode;
+}) => (
+  <Card p={5} maxW="420px" bg="bg.surface">
+    <Text fontWeight="bold" mb={1} color="fg.default">
+      {title}
+    </Text>
+    <Text fontSize="sm" color="fg.muted" mb={5}>
+      {body}
+    </Text>
+    <Flex gap={2} justify="flex-end">
+      {children}
+    </Flex>
+  </Card>
+);
+
+export const DoOnePrimary: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: one primary, secondary to its left',
+  render: () => (
+    <Panel title="그룹 이름 변경" body="변경한 이름은 모든 멤버에게 보입니다.">
+      <Button variant="secondary">취소</Button>
+      <Button variant="primary">저장</Button>
+    </Panel>
+  ),
+};
+
+export const DontTwoPrimaries: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: two primaries side by side",
+  render: () => (
+    <Panel title="그룹 이름 변경" body="변경한 이름은 모든 멤버에게 보입니다.">
+      <Button variant="primary">취소</Button>
+      <Button variant="primary">저장</Button>
+    </Panel>
+  ),
+};
+
+export const DoDangerToConfirm: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: danger fill only on the confirming button',
+  render: () => (
+    <Panel
+      title="챗봇을 삭제할까요?"
+      body="삭제한 챗봇과 대화 기록은 되돌릴 수 없습니다."
+    >
+      <Button variant="secondary">취소</Button>
+      <Button variant="danger">삭제</Button>
+    </Panel>
+  ),
+};
+
+const ROWS = ['마케팅 챗봇', '영업 챗봇', '사내 규정 챗봇'];
+
+const Row = ({ name, action }: { name: string; action: ReactNode }) => (
+  <Flex
+    justify="space-between"
+    align="center"
+    py={2}
+    borderBottomWidth="1px"
+    borderColor="border.subtle"
+  >
+    <Text fontSize="sm" color="fg.default">
+      {name}
+    </Text>
+    {action}
+  </Flex>
+);
+
+export const DoQuietDestructiveInRows: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: isDestructive on a quiet button in a list',
+  render: () => (
+    <Box maxW="420px">
+      {ROWS.map((name) => (
+        <Row
+          key={name}
+          name={name}
+          action={
+            <Button variant="ghost" size="sm" isDestructive>
+              <TrashIcon />
+              삭제
+            </Button>
+          }
+        />
+      ))}
+    </Box>
+  ),
+};
+
+export const DontDangerFillInRows: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a red fill on every row",
+  render: () => (
+    <Box maxW="420px">
+      {ROWS.map((name) => (
+        <Row
+          key={name}
+          name={name}
+          action={
+            <Button variant="danger" size="sm">
+              삭제
+            </Button>
+          }
+        />
+      ))}
+    </Box>
+  ),
+};
+
+export const DoPrimaryForUpgrade: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: primary for upgrade and payment',
+  render: () => (
+    <Panel
+      title="크레딧이 부족합니다"
+      body="요금제를 올리면 이번 달 남은 기간에도 바로 쓸 수 있습니다."
+    >
+      <Button variant="secondary">나중에</Button>
+      <Button variant="primary">요금제 업그레이드</Button>
+    </Panel>
+  ),
+};
+
+export const DontAccentForUpgrade: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: coral accent for upgrade in the product",
+  render: () => (
+    <Panel
+      title="크레딧이 부족합니다"
+      body="요금제를 올리면 이번 달 남은 기간에도 바로 쓸 수 있습니다."
+    >
+      <Button variant="secondary">나중에</Button>
+      <Button variant="accent">요금제 업그레이드</Button>
+    </Panel>
+  ),
+};
+
+export const DoLoadingText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: loadingText while the action runs',
+  render: () => (
+    <HStack gap={4}>
+      <Button variant="primary" loading loadingText="저장 중">
+        저장
+      </Button>
+      <Button variant="action" loading loadingText="실행 중">
+        <Sparkles />
+        실행
+      </Button>
+    </HStack>
+  ),
+};
+
+export const DontSpinnerOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a spinner with no words",
+  render: () => (
+    <HStack gap={4}>
+      <Button variant="primary" loading>
+        저장
+      </Button>
+    </HStack>
+  ),
+};
+
+type StateStyles = {
+  bgColor?: unknown;
+  borderColor?: unknown;
+  color?: unknown;
+  _hover?: unknown;
+  _active?: unknown;
+};
+
+const STATE_LABELS = {
+  bgColor: { en: 'fill', ko: '바탕' },
+  borderColor: { en: 'border', ko: '테두리' },
+  color: { en: 'label', ko: '글자' },
+  hover: { en: 'hover fill', ko: '마우스 올림' },
+  active: { en: 'pressed fill', ko: '누름' },
+} as const;
+
+type Use = { en: string; ko: string };
+
+/**
+ * One row per token, listing every role and state that reads it. Read from
+ * `buttonVariantStyles`, so a recipe change shows up here on the next build.
+ */
+const buttonTokenRows = () => {
+  const uses = new Map<string, Use[]>();
+  const add = (token: unknown, use: Use) => {
+    if (typeof token !== 'string' || token === 'transparent') return;
+    uses.set(token, [...(uses.get(token) ?? []), use]);
+  };
+  buttonVariants.forEach((variant) => {
+    const s = buttonVariantStyles[variant] as StateStyles;
+    const label = (key: keyof typeof STATE_LABELS) => ({
+      en: `${variant} ${STATE_LABELS[key].en}`,
+      ko: `${variant} ${STATE_LABELS[key].ko}`,
+    });
+    add(s.bgColor, label('bgColor'));
+    add(s.borderColor, label('borderColor'));
+    add(s.color, label('color'));
+    add((s._hover as StateStyles | undefined)?.bgColor, label('hover'));
+    add((s._active as StateStyles | undefined)?.bgColor, label('active'));
+  });
+  add('action.iconOnSolid', { en: 'action icon', ko: 'action 아이콘' });
+  add('danger.fg', {
+    en: 'isDestructive label',
+    ko: 'isDestructive 글자',
+  });
+  add('disabled.bg', { en: 'disabled fill', ko: '비활성 바탕' });
+  add('disabled.fg', { en: 'disabled label', ko: '비활성 글자' });
+  add('disabled.fgGhost', {
+    en: 'ghost disabled label',
+    ko: 'ghost 비활성 글자',
+  });
+  add('focus.ring', { en: 'keyboard focus ring', ko: '키보드 초점 링' });
+  return [...uses].map(([token, list]) => ({
+    token,
+    use: (
+      <T
+        en={list.map((u) => u.en).join(', ')}
+        ko={list.map((u) => u.ko).join(', ')}
+      />
+    ),
+  }));
+};
+
+/** Every token a role reads at rest, on hover and on press. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => <TokenTable rows={buttonTokenRows()} />,
+};

package/src/components/Button/Button.tsx

@@ -1,6 +1,7 @@
-import { forwardRef } from 'react';
+import { forwardRef, MouseEvent } from 'react';
 import { Button as ChakraButton, SystemStyleObject } from '@chakra-ui/react';
 
+import { useTranslate } from '@/hooks/useTranslate';
 import { focusRing } from '@/utils/focusRing';
 import { mergeCss } from '@/utils/mergeCss';
 
@@ -37,6 +38,10 @@ const ButtonImpl = forwardRef<HTMLButtonElement, ButtonProps>(
       isDestructive: isDestructiveProp = false,
       size,
       lift,
+      disabled,
+      focusableWhenDisabled = false,
+      onDisabledClick,
+      onClick,
       children,
       _hover: hoverProp,
       _active: activeProp,
@@ -49,8 +54,19 @@ const ButtonImpl = forwardRef<HTMLButtonElement, ButtonProps>(
     // 4.x callers (untyped JS, `as any`) can still hand us `colorPalette` and
     // an old variant name. Strip it so it never reaches Chakra's own recipe,
     // and map the pair onto a 5.0 role — see `Button.legacy.ts`.
-    const { colorPalette: legacyPalette, ...rest } =
-      restWithLegacy as typeof restWithLegacy & { colorPalette?: unknown };
+    const {
+      colorPalette: legacyPalette,
+      loadingText: loadingTextProp,
+      ...rest
+    } = restWithLegacy as typeof restWithLegacy & { colorPalette?: unknown };
+    // A busy button says what it is doing: 처리 중 unless the call site names
+    // the verb (저장 중). `loadingText={null}` opts out — spinner only, and the
+    // button keeps its width.
+    const translate = useTranslate();
+    const loadingText =
+      loadingTextProp === undefined
+        ? translate('processing')
+        : (loadingTextProp ?? undefined);
 
     let variant: ButtonVariant = variantProp ?? 'subtle';
     let isDestructive = isDestructiveProp;
@@ -67,6 +83,24 @@ const ButtonImpl = forwardRef<HTMLButtonElement, ButtonProps>(
 
     const base = getButtonStyles(variant, isDestructive);
 
+    // `focusableWhenDisabled`: disabled by ARIA, not by the attribute, so the
+    // button stays focusable and can answer a press. `aria-disabled=true` is
+    // in Chakra's `_disabled` condition, so the disabled colours and cursor
+    // still apply; `data-disabled` is what `_hover` / `_active` exclude, so
+    // without it the button would still react to the pointer. `loading` keeps
+    // the native attribute (Chakra sets it) — see `focusableWhenDisabled`.
+    const softDisabled = !!disabled && focusableWhenDisabled && !rest.loading;
+    const handleClick = softDisabled
+      ? (event: MouseEvent<HTMLButtonElement>) => {
+          // Also what stops a `type="submit"` button from submitting.
+          event.preventDefault();
+          // A native disabled button sends no click to its ancestors either —
+          // a clickable row around it must not run its own action.
+          event.stopPropagation();
+          onDisabledClick?.(event);
+        }
+      : onClick;
+
     // Merged rather than spread after: each variant already owns `_hover` and
     // `_active` for its colours, and replacing either would drop them.
     const styles = lift
@@ -149,7 +183,16 @@ const ButtonImpl = forwardRef<HTMLButtonElement, ButtonProps>(
         ref={ref}
         data-variant={variant}
         data-destructive={isDestructive || undefined}
+        loadingText={loadingText}
+        disabled={softDisabled ? undefined : disabled}
+        onClick={handleClick}
         {...rest}
+        // After `rest`, so a stray `aria-disabled` / `data-disabled` from the
+        // call site or a merging `asChild` parent cannot undo it.
+        {...(softDisabled && {
+          'aria-disabled': true,
+          'data-disabled': '',
+        })}
         // The `action` icon rule lives in `css` (a nested selector cannot be a
         // style prop); merged so a call site's `css` adds to it.
         css={mergeCss(base.css as SystemStyleObject | undefined, cssProp)}

package/src/components/Button/Button.types.ts

@@ -1,4 +1,4 @@
-import type { ElementType } from 'react';
+import type { ElementType, MouseEvent } from 'react';
 import { ButtonProps as ChakraButtonProps } from '@chakra-ui/react';
 
 // Relative, NOT `@/types/polymorphic`. Path aliases survive into the emitted
@@ -107,6 +107,43 @@ export type ButtonOwnProps = Omit<
    * @default false
    */
   lift?: boolean;
+  /**
+   * Keeps a `disabled` button in the Tab order and lets it receive clicks, so
+   * the screen can say *why* it is disabled.
+   *
+   * A natively `disabled` `<button>` cannot be focused and swallows every
+   * click: a keyboard or screen reader user may never find it, and a mouse
+   * user who presses it gets no answer at all. With this prop, `disabled`
+   * renders as `aria-disabled="true"` (plus `data-disabled`) instead of the
+   * native attribute:
+   *
+   * - the disabled colours, the `not-allowed` cursor and the "no hover, no
+   *   press" behaviour are the same as a native disabled button;
+   * - Tab still reaches it and the focus ring shows;
+   * - activating it (click, Enter, Space) does **not** call `onClick`, and its
+   *   default action is cancelled, so a `type="submit"` button does not submit
+   *   its form; the click does not bubble to ancestors; `onDisabledClick` is
+   *   called instead.
+   *
+   * Only activation is blocked: other handlers (`onKeyDown`, `onPointerDown`,
+   * …) still run, as they would on any focusable element. Inside a trigger
+   * (`Menu.Trigger asChild`, `Popover.Trigger asChild`) disable the root as
+   * well. Meant for `<button>`: with `as="a"` the `href` stays, so middle-click
+   * still opens it.
+   *
+   * Has no effect unless `disabled` is set. `loading` keeps the native
+   * `disabled` — a busy button is working, not refusing.
+   *
+   * @default false
+   */
+  focusableWhenDisabled?: boolean;
+  /**
+   * Called when a `disabled` + `focusableWhenDisabled` button is activated
+   * (click, Enter, Space) — where `onClick` would have been. Use it to explain
+   * the reason or move focus to what is missing (an unticked consent box).
+   * Never called on a natively disabled button, and never while `loading`.
+   */
+  onDisabledClick?: (event: MouseEvent<HTMLButtonElement>) => void;
 };
 
 /**