@mindlogic-ai/logician-ui 5.0.0-alpha.2 → 5.0.0-alpha.21

package/src/guidelines/_components/Lang.tsx

@@ -0,0 +1,175 @@
+/**
+ * Doc-only language switch for the Storybook guideline pages.
+ *
+ * One MDX file carries both languages: wrap each block in `<En>` / `<Ko>` and
+ * put `<LangToggle />` at the top of the page. The choice is kept in
+ * localStorage (default English) and every block on the page — and on every
+ * other guideline page — follows it.
+ *
+ * Not part of the published library: nothing in `src/index.ts` imports it,
+ * `check-component-exports.js` only scans `src/components`, and the rollup
+ * build excludes `src/guidelines/**`.
+ */
+import { ReactNode, useSyncExternalStore } from 'react';
+
+type DocLang = 'en' | 'ko';
+
+const STORAGE_KEY = 'logician-ui:docs-lang';
+const listeners = new Set<() => void>();
+let current: DocLang | undefined;
+
+const read = (): DocLang => {
+  try {
+    return window.localStorage.getItem(STORAGE_KEY) === 'ko' ? 'ko' : 'en';
+  } catch {
+    return 'en';
+  }
+};
+
+const write = (lang: DocLang) => {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, lang);
+  } catch {
+    // Storage blocked (private mode): the switch still works for this page.
+  }
+  current = lang;
+  listeners.forEach((notify) => notify());
+};
+
+const snapshot = (): DocLang => (current ??= read());
+
+// Another tab changed it: one listener for the whole page, not one per block.
+const onStorage = (event: StorageEvent) => {
+  if (event.key !== STORAGE_KEY) return;
+  current = read();
+  listeners.forEach((notify) => notify());
+};
+
+const subscribe = (notify: () => void) => {
+  if (listeners.size === 0) window.addEventListener('storage', onStorage);
+  listeners.add(notify);
+  return () => {
+    listeners.delete(notify);
+    if (listeners.size === 0) window.removeEventListener('storage', onStorage);
+  };
+};
+
+/** The language the reader picked; `'en'` until they pick one. */
+const useDocLang = (): DocLang =>
+  useSyncExternalStore(subscribe, snapshot, () => 'en');
+
+const pick = <V,>(lang: DocLang, en: V, ko: V) => (lang === 'ko' ? ko : en);
+
+const Block = ({ lang, children }: { lang: DocLang; children: ReactNode }) =>
+  useDocLang() === lang ? <div lang={lang}>{children}</div> : null;
+
+/** English block. Leave a blank line after the opening tag so Markdown parses. */
+export const En = ({ children }: { children: ReactNode }) => (
+  <Block lang="en">{children}</Block>
+);
+
+/** Korean block. Leave a blank line after the opening tag so Markdown parses. */
+export const Ko = ({ children }: { children: ReactNode }) => (
+  <Block lang="ko">{children}</Block>
+);
+
+/** Inline text in the reader's language, for captions and table cells. */
+export const T = ({ en, ko }: { en: ReactNode; ko: ReactNode }) => {
+  const lang = useDocLang();
+  return <span lang={lang}>{pick(lang, en, ko)}</span>;
+};
+
+const OPTIONS: { value: DocLang; label: string }[] = [
+  { value: 'en', label: 'English' },
+  { value: 'ko', label: '한국어' },
+];
+
+/** Top-of-page switch. Renders as a two-button segmented control. */
+export const LangToggle = () => {
+  const lang = useDocLang();
+  return (
+    <div
+      role="group"
+      aria-label="Language / 언어"
+      style={{
+        display: 'inline-flex',
+        border: '1px solid #D8D2CA',
+        borderRadius: 8,
+        overflow: 'hidden',
+        margin: '0 0 16px',
+        fontSize: 13,
+      }}
+    >
+      {OPTIONS.map((option) => {
+        const active = option.value === lang;
+        return (
+          <button
+            key={option.value}
+            type="button"
+            lang={option.value}
+            aria-pressed={active}
+            onClick={() => write(option.value)}
+            style={{
+              padding: '6px 14px',
+              border: 0,
+              cursor: 'pointer',
+              fontWeight: active ? 700 : 400,
+              background: active ? '#252525' : 'transparent',
+              color: active ? '#F5EDE0' : '#252525',
+            }}
+          >
+            {option.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+};
+
+const VERDICT = {
+  do: {
+    mark: '✓',
+    en: 'Do',
+    ko: '이렇게 하세요',
+    rule: '#5E7A37',
+    ink: '#425C17',
+  },
+  dont: {
+    mark: '×',
+    en: "Don't",
+    ko: '이렇게 하지 마세요',
+    rule: '#A02525',
+    ink: '#A02525',
+  },
+};
+
+/** Do / Don't caption under a `<Canvas>` specimen. */
+export const Verdict = ({
+  kind,
+  en,
+  ko,
+}: {
+  kind: 'do' | 'dont';
+  en: ReactNode;
+  ko: ReactNode;
+}) => {
+  const lang = useDocLang();
+  const v = VERDICT[kind];
+  return (
+    <p
+      lang={lang}
+      style={{
+        margin: '-12px 0 28px',
+        paddingLeft: 12,
+        borderLeft: `3px solid ${v.rule}`,
+        fontSize: 14,
+        lineHeight: 1.6,
+      }}
+    >
+      <strong style={{ color: v.ink }}>
+        {v.mark} {pick(lang, v.en, v.ko)}.
+      </strong>{' '}
+      {pick(lang, en, ko)}
+    </p>
+  );
+};

package/src/guidelines/_components/TokenTable.tsx

@@ -0,0 +1,136 @@
+/**
+ * Doc-only token table for guideline pages: one row per semantic token, with
+ * its light and dark value resolved from the shipped theme
+ * (`getSwatchGroups` in `src/theme/paletteSwatches.ts`). No hex is written by
+ * hand, so a palette change shows up here on the next build.
+ *
+ * Render it inside a story (it uses Chakra), then pull the story into MDX with
+ * `<Canvas of={…} />` or `<Story of={…} />`. Not exported from the library.
+ */
+import type { ReactNode } from 'react';
+import { Box, Grid } from '@chakra-ui/react';
+import { readableColor } from 'polished';
+
+import { getSwatchGroups, Swatch } from '../../theme/paletteSwatches';
+import { T } from './Lang';
+
+const SWATCHES: ReadonlyMap<string, Swatch> = new Map(
+  getSwatchGroups().flatMap(([, swatches]) =>
+    swatches.map((swatch) => [swatch.path, swatch] as const)
+  )
+);
+
+/** Light and dark hex of a public semantic token. Throws on an unknown name. */
+const resolveToken = (path: string): Swatch => {
+  const swatch = SWATCHES.get(path);
+  if (!swatch) throw new Error(`Unknown semantic colour token: ${path}`);
+  return swatch;
+};
+
+/** Label colour for a chip: brand black or white, whichever reads on it. */
+const labelOn = (hex: string) =>
+  readableColor(hex, '#252525', '#FFFFFF', false);
+
+const Chip = ({ hex }: { hex: string }) => {
+  const transparent = !/^#/.test(hex);
+  return (
+    <Box
+      // Literal values, not tokens: the chip shows one fixed mode's value
+      // whatever mode the page is in.
+      style={{
+        background: transparent ? undefined : hex,
+        color: transparent ? undefined : labelOn(hex),
+      }}
+      borderWidth="1px"
+      borderColor="border.subtle"
+      borderStyle={transparent ? 'dashed' : 'solid'}
+      borderRadius="sm"
+      px={2}
+      py={1.5}
+      fontFamily="mono"
+      fontSize="11px"
+      minW="88px"
+    >
+      {hex.replace('#', '')}
+    </Box>
+  );
+};
+
+type TokenRow = {
+  /** Semantic token path, e.g. `primary.main`. */
+  token: string;
+  /** What the token is for, in the reader's language. */
+  use?: ReactNode;
+};
+
+const HEADERS: ReactNode[] = [
+  <T key="token" en="Token" ko="토큰" />,
+  <T key="light" en="Light" ko="라이트" />,
+  <T key="dark" en="Dark" ko="다크" />,
+  <T key="use" en="Use" ko="쓰는 곳" />,
+];
+
+/**
+ * Token | light | dark | use. Pass `rows` as token names or `{ token, use }`;
+ * `use` is usually a `<T en ko />` so it follows the page language.
+ */
+export const TokenTable = ({ rows }: { rows: (string | TokenRow)[] }) => {
+  const normalised = rows.map((row) =>
+    typeof row === 'string' ? { token: row } : row
+  );
+  const hasUse = normalised.some((row) => row.use);
+  return (
+    <Grid
+      templateColumns={{
+        base: 'minmax(0,1fr) auto auto',
+        md: hasUse
+          ? 'minmax(160px,auto) auto auto minmax(0,1fr)'
+          : 'minmax(160px,auto) auto auto',
+      }}
+      columnGap={3}
+      rowGap={1.5}
+      alignItems="center"
+      justifyContent="start"
+      fontSize="13px"
+      color="fg.default"
+      maxW="100%"
+    >
+      {HEADERS.slice(0, hasUse ? 4 : 3).map((header, i) => (
+        <Box
+          key={i}
+          fontWeight="bold"
+          color="fg.subtle"
+          display={i === 3 ? { base: 'none', md: 'block' } : undefined}
+        >
+          {header}
+        </Box>
+      ))}
+      {normalised.map(({ token, use }) => {
+        const { light, dark } = resolveToken(token);
+        return (
+          <Box key={token} display="contents">
+            <Box fontFamily="mono" fontSize="12px" wordBreak="break-all">
+              {token}
+              {use && (
+                <Box
+                  display={{ base: 'block', md: 'none' }}
+                  fontFamily="body"
+                  color="fg.subtle"
+                >
+                  {use}
+                </Box>
+              )}
+            </Box>
+            <Chip hex={light} />
+            <Chip hex={dark} />
+            {hasUse && (
+              <Box display={{ base: 'none', md: 'block' }} color="fg.muted">
+                {use}
+              </Box>
+            )}
+          </Box>
+        );
+      })}
+    </Grid>
+  );
+};

package/src/hooks/useLanguage.ts

@@ -8,9 +8,14 @@ export interface LanguageContextValue {
   language: SupportedLanguage;
 }
 
-export const LanguageContext = createContext<LanguageContextValue>({
-  language: 'en',
-});
+/**
+ * The value seen outside any `LogicianProvider`. Exported so `useTranslate`
+ * can tell "no provider" (keep Korean) from a provider set to `en`.
+ */
+export const NO_PROVIDER_LANGUAGE: LanguageContextValue = { language: 'en' };
+
+export const LanguageContext =
+  createContext<LanguageContextValue>(NO_PROVIDER_LANGUAGE);
 
 export const useLanguage = () => useContext(LanguageContext);
 

package/src/hooks/useTranslate.test.tsx

@@ -0,0 +1,46 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render, screen } from '@testing-library/react';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { Button } from '@/components/Button';
+import { LogicianProvider } from '@/components/LogicianProvider';
+import { system } from '@/theme';
+
+beforeAll(() => {
+  // LogicianProvider's color-mode machinery calls it on mount; jsdom has none.
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  })) as unknown as typeof window.matchMedia;
+});
+
+// Read through Button's 처리 중 default, the string an app sees most.
+describe('useTranslate follows LogicianProvider language', () => {
+  it('stays Korean outside a provider', () => {
+    render(
+      <ChakraProvider value={system}>
+        <Button loading>x</Button>
+      </ChakraProvider>
+    );
+    expect(screen.getByRole('button')).toHaveTextContent('처리 중');
+  });
+
+  it.each([
+    ['ko', '처리 중'],
+    ['en', 'Processing'],
+    ['ja', '処理中'],
+  ] as const)('renders %s', (language, text) => {
+    render(
+      <LogicianProvider language={language} loadFonts={false}>
+        <Button loading>x</Button>
+      </LogicianProvider>
+    );
+    expect(screen.getByRole('button')).toHaveTextContent(text);
+  });
+});

package/src/hooks/useTranslate.ts

@@ -3,6 +3,7 @@ import { useCallback } from 'react';
 
 import defaultTranslations from '../translations/Defaults.translations.json';
 import { formatForMarkdown } from '../utils/formatTextForMarkdown';
+import { NO_PROVIDER_LANGUAGE, useLanguage } from './useLanguage';
 
 const DEFAULT_LOCALE = 'ko';
 
@@ -38,12 +39,13 @@ const replaceVariables = (text: string, variables?: { [key: string]: any }) => {
     : parts;
 };
 
-const getLanguage = () => {
-  return 'ko';
-};
-
 export const useTranslate = (translations = {}) => {
-  const userLanguage = getLanguage();
+  // Follow `LogicianProvider`'s `language`, the same one the date pickers
+  // read. Outside a provider there is nothing to follow, so the library keeps
+  // its historical Korean.
+  const context = useLanguage();
+  const userLanguage =
+    context === NO_PROVIDER_LANGUAGE ? DEFAULT_LOCALE : context.language;
   return useCallback(
     (key: string, variables?: { [key: string]: any }) => {
       const locale = (userLanguage as string) ?? DEFAULT_LOCALE;

package/src/index.ts

@@ -66,6 +66,7 @@ export * from './components/MonthPicker';
 export * from './components/Popover';
 
 // Navigation Components
+export * from './components/NavList';
 export * from './components/Pagination';
 
 // Input Variants
@@ -178,7 +179,12 @@ export {
 } from './theme/motion';
 export { cubicBezier } from './utils/cubicBezier';
 export { disabledControl, disabledText } from './utils/disabledControl';
-export { FOCUS_RING_SHADOW, focusRing } from './utils/focusRing';
+export {
+  FOCUS_RING_INSET_SHADOW,
+  FOCUS_RING_SHADOW,
+  focusRing,
+  focusRingInset,
+} from './utils/focusRing';
 export {
   staggerDelayMs,
   type StaggerProps,

package/src/theme/BazePalette.stories.tsx

@@ -7,7 +7,19 @@ import {
   ROLE_TOKEN_PATHS,
   SYSTEM_HUE_NAMES,
 } from './colors';
-import { CORAL, RAMPS, SCHEMES, SYSTEM_HUES } from './palette.generated';
+import {
+  CORAL,
+  DATAVIZ,
+  RAMPS,
+  SCHEMES,
+  SYSTEM_HUES,
+} from './palette.generated';
+import {
+  DATA_VIZ_LABEL_TOKEN,
+  DATA_VIZ_LABELS,
+  type DataVizKey,
+  resolveColor,
+} from './paletteSwatches';
 
 /**
  * logician-ui 5.0 BAZE palette — the three token layers.
@@ -104,6 +116,12 @@ export const RawScales: Story = {
           <Chip key={k} hex={hex} label={k} />
         ))}
       </Flex>
+      <H4>dataviz</H4>
+      <Flex gap={2} wrap="wrap">
+        {Object.entries(DATAVIZ).map(([k, hex]) => (
+          <Chip key={k} hex={hex} label={k} />
+        ))}
+      </Flex>
       <H4>system hues</H4>
       <Grid templateColumns="120px repeat(8, 1fr)" gap={1} fontSize="11px">
         <span />
@@ -157,6 +175,98 @@ export const RoleTokens: Story = {
   ),
 };
 
+const DATA_STEPS = (Object.keys(DATA_VIZ_LABELS) as DataVizKey[]).filter((k) =>
+  k.startsWith('data-')
+);
+/** Display order: far below → baseline → far above. */
+const DIVERGING_STEPS: DataVizKey[] = [
+  'diverging-neg-3',
+  'diverging-neg-2',
+  'diverging-neg-1',
+  'diverging-mid',
+  'diverging-pos-1',
+  'diverging-pos-2',
+  'diverging-pos-3',
+];
+
+/** A fill with the in-cell label `DATA_VIZ_LABELS` gives it (or none). */
+const DataCell = ({
+  flat,
+  hex,
+  mode,
+}: {
+  flat: DataVizKey;
+  hex: string;
+  mode: 'light' | 'dark';
+}) => {
+  const label = DATA_VIZ_LABELS[flat][mode];
+  const labelHex =
+    label && resolveColor(`{colors.${DATA_VIZ_LABEL_TOKEN[label]}}`, mode);
+  return (
+    <Stack gap={1}>
+      <Flex
+        bg={hex}
+        color={labelHex || undefined}
+        h="56px"
+        align="center"
+        justify="center"
+        fontSize="13px"
+        fontWeight="bold"
+        borderRadius="sm"
+      >
+        {labelHex && '42%'}
+      </Flex>
+      {/* Plain boxes: the panel paints its own mode, so text inherits its colour. */}
+      <Box fontFamily="mono" fontSize="11px">
+        {ROLE_TOKEN_PATHS[flat]}
+      </Box>
+      <Box fontSize="10px">
+        {hex} ·{' '}
+        {labelHex
+          ? `${label} label ${ratio(hex, labelHex).toFixed(2)}`
+          : 'no in-cell label'}
+      </Box>
+    </Stack>
+  );
+};
+
+/**
+ * Data-visualisation fills — `data.1–4` (single measure, 4 = largest) and
+ * `diverging.*` (blue above the baseline, orange below, `diverging.mid` at it)
+ * — in light and dark, each with the in-cell label it can carry.
+ */
+export const DataViz: Story = {
+  render: () => (
+    <Stack gap={6} maxW="1100px">
+      {(['light', 'dark'] as const).map((mode) => {
+        const table = SCHEMES.ink[mode] as Record<string, string>;
+        return (
+          <Stack
+            key={mode}
+            gap={4}
+            p={4}
+            borderRadius="md"
+            bg={table['bg-canvas']}
+            color={table['fg-default']}
+          >
+            <Box fontWeight="bold">{mode}</Box>
+            <Grid templateColumns="repeat(4, 1fr)" gap={2}>
+              {DATA_STEPS.map((k) => (
+                <DataCell key={k} flat={k} hex={table[k]} mode={mode} />
+              ))}
+            </Grid>
+            <Grid templateColumns="repeat(7, 1fr)" gap={2}>
+              {DIVERGING_STEPS.map((k) => (
+                <DataCell key={k} flat={k} hex={table[k]} mode={mode} />
+              ))}
+            </Grid>
+          </Stack>
+        );
+      })}
+    </Stack>
+  ),
+};
+
 /** Live tokens on this page's colour mode — flip the toolbar to check dark. */
 export const Category: Story = {
   render: () => (

package/src/theme/Palette.stories.tsx

@@ -30,9 +30,9 @@ const meta = {
 
 Three layers; components read only the last one.
 
-1. **Raw scales** — \`ink\` / \`inkDark\`, \`sand\` / \`sandDark\`, \`slate\` / \`slateDark\` (1–12), \`coral\`, and 12 system hues. Values come from \`scripts/palette/generate.mjs\`.
+1. **Raw scales** — \`ink\` / \`inkDark\`, \`sand\` / \`sandDark\`, \`slate\` / \`slateDark\` (1–12), \`coral\`, 12 system hues, and \`dataviz\`. Values come from \`scripts/palette/generate.mjs\`.
 2. **Semantic steps** — \`neutral.1–12\` and \`secondary.1–12\`, filled by the theme option: \`createLogicianTheme({ neutral: 'ink' | 'slate', secondary: 'sand' })\` (or \`<LogicianProvider theme={…}>\`).
-3. **Role tokens** — \`bg.*\`, \`layer.*\`, \`fg.*\`, \`border.*\`, \`primary.*\`, \`action.*\`, status \`{bg,border,fg,solid,onSolid}\`, \`category.*\` …
+3. **Role tokens** — \`bg.*\`, \`layer.*\`, \`fg.*\`, \`border.*\`, \`primary.*\`, \`action.*\`, status \`{bg,border,fg,solid,onSolid}\`, \`category.*\`, data-viz fills \`data.*\` / \`diverging.*\` …
 
 Every value below is shown in light and dark. Contrast is audited in CI (\`contrast.test.ts\`) in light, dark and both high-contrast modes. The 4.x names still resolve as aliases until 6.0 and are listed at the bottom, not in the grid. Setup/Theme/BAZE Palette shows the raw scales and every role in all four modes.
         `,