@mindlogic-ai/logician-ui 4.0.0-alpha.9 → 4.0.0

package/src/components/FlyTo/FlyTo.stories.tsx

@@ -0,0 +1,157 @@
+import { Box, HStack, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+import { useRef, useState } from 'react';
+
+import { Button } from '../Button';
+import { Subtext, Text } from '../Typography';
+import { FlyTo } from '.';
+
+/**
+ * Sends a ghost arcing from one rect to another — "this went there".
+ *
+ * JavaScript measures; CSS animates. The two rects are only knowable at
+ * runtime, so the distance is computed and handed to a keyframe as three custom
+ * properties — the arc itself runs on the compositor with no frame loop.
+ */
+/**
+ * Untyped against the component on purpose: `from` and `to` are `DOMRect`s
+ * measured at runtime, so there is no static `args` to satisfy — every story
+ * here has to render its own instance after laying the two elements out.
+ */
+const meta = {
+  title: 'Components/Motion/FlyTo',
+  component: FlyTo,
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+const Chip = () => (
+  <HStack
+    gap={1}
+    bg="primary.main"
+    color="fg.inverse"
+    px={3}
+    py={1}
+    borderRadius="full"
+    fontSize="sm"
+    fontWeight="700"
+  >
+    <Box>◆</Box>
+    <Box>+50</Box>
+  </HStack>
+);
+
+/**
+ * The caller owns mounting. `onDone` is what advances the sequence — a reward
+ * that landed has to update a balance, and that happens when the ghost arrives
+ * rather than when it left.
+ */
+export const Default: Story = {
+  render: () => {
+    const source = useRef<HTMLButtonElement>(null);
+    const target = useRef<HTMLDivElement>(null);
+    const [flight, setFlight] = useState<{ from: DOMRect; to: DOMRect } | null>(
+      null
+    );
+    const [balance, setBalance] = useState(1250);
+
+    return (
+      <Stack gap={6}>
+        <HStack gap={12} justify="space-between" maxW="480px" align="center">
+          <Button
+            ref={source}
+            size="sm"
+            onClick={() => {
+              const from = source.current?.getBoundingClientRect();
+              const to = target.current?.getBoundingClientRect();
+              if (from && to) setFlight({ from, to });
+            }}
+          >
+            보내기
+          </Button>
+
+          <Box ref={target} textAlign="right">
+            <Subtext color="fg.muted" fontSize="2xs" mb={0}>
+              잔액
+            </Subtext>
+            <Text fontSize="xl" fontWeight="700" mb={0}>
+              {balance.toLocaleString()}
+            </Text>
+          </Box>
+        </HStack>
+
+        {flight && (
+          <FlyTo
+            from={flight.from}
+            to={flight.to}
+            onDone={() => {
+              setFlight(null);
+              setBalance((b) => b + 50);
+            }}
+          >
+            <Chip />
+          </FlyTo>
+        )}
+
+        <Subtext color="fg.muted" mb={0}>
+          잔액은 타이머가 아니라 착지 시점에 오릅니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};
+
+/** `lift` is how high the arc rises above the straight line between the rects. */
+export const Lift: Story = {
+  render: () => {
+    const source = useRef<HTMLButtonElement>(null);
+    const target = useRef<HTMLDivElement>(null);
+    const [lift, setLift] = useState<number | null>(null);
+
+    const send = (value: number) => {
+      const from = source.current?.getBoundingClientRect();
+      const to = target.current?.getBoundingClientRect();
+      if (from && to) setLift(value);
+    };
+
+    return (
+      <Stack gap={6}>
+        <HStack gap={2}>
+          {[0, 46, 120].map((v) => (
+            <Button key={v} size="xs" variant="outline" onClick={() => send(v)}>
+              lift {v}
+            </Button>
+          ))}
+        </HStack>
+
+        <HStack gap={12} justify="space-between" maxW="480px" align="center">
+          <Button ref={source} size="sm" variant="ghost">
+            출발
+          </Button>
+          <Box ref={target} px={3} py={2} borderRadius="md" bg="bg.subtle">
+            도착
+          </Box>
+        </HStack>
+
+        {lift !== null && source.current && target.current && (
+          <FlyTo
+            key={lift}
+            from={source.current.getBoundingClientRect()}
+            to={target.current.getBoundingClientRect()}
+            lift={lift}
+            onDone={() => setLift(null)}
+          >
+            <Chip />
+          </FlyTo>
+        )}
+
+        <Subtext color="fg.muted" mb={0}>
+          <b>0이면 직선</b>이고, 직선 보간은 던진 것이 아니라 레이아웃이 바뀐
+          것으로 읽힙니다. 궤적이 이 프리미티브의 전부입니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};

package/src/components/FlyTo/FlyTo.styles.ts

@@ -0,0 +1,31 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+/**
+ * The ghost in flight.
+ *
+ * `position: fixed` and a portal, so the flight is measured in the same
+ * coordinate space as the two `getBoundingClientRect()` calls that defined it,
+ * and so no ancestor's `overflow: hidden` clips a chip halfway across the page.
+ *
+ * `motion.slow`, the band for a move that carries the eye somewhere — the
+ * ghost has to be *followed* to do its job, which is longer than any transition
+ * and shorter than the celebration it usually precedes.
+ *
+ * `standard` rather than `emphasized`: the house ease-out covers 96% of the
+ * distance in the first half, which on an arc means the piece is already at the
+ * target while the curve is still lifting it. A symmetric curve keeps the two
+ * halves of the arc the same shape, which is what makes it read as thrown.
+ */
+export const flyGhost: SystemStyleObject = {
+  position: 'fixed',
+  zIndex: 'toast',
+  pointerEvents: 'none',
+  display: 'inline-flex',
+  animationName: 'fly-arc',
+  animationDuration: 'motion.slow',
+  animationTimingFunction: 'standard',
+  animationFillMode: 'forwards',
+  // The component returns `null` before this can apply — kept so the guard
+  // survives a future caller that renders the ghost some other way.
+  _motionReduce: { animationName: 'none', opacity: 0 },
+};

package/src/components/FlyTo/FlyTo.tsx

@@ -0,0 +1,88 @@
+import { ForwardedRef, forwardRef, useEffect } from 'react';
+import { Box, Portal, useBreakpointValue } from '@chakra-ui/react';
+
+import { flyGhost } from './FlyTo.styles';
+import { FlyToProps } from './FlyTo.types';
+
+/**
+ * Sends a ghost arcing from one rect to another — "this went there". A reward
+ * chip flying into a balance, a file into a folder, a row into a bin.
+ *
+ * Mount it to fly; it calls `onDone` on landing and the caller unmounts it. The
+ * caller owns the lifecycle because only the caller knows what the flight
+ * means: a reward that landed has to update a balance, and that has to happen
+ * when the ghost arrives rather than when it left.
+ *
+ * **JavaScript measures; CSS animates.** The two rects are only knowable at
+ * runtime, so the distance is computed here — but it is handed to the keyframe
+ * as three custom properties, and the arc itself runs on the compositor with no
+ * frame loop and no animation library. FactChat's version drives the same arc
+ * through framer-motion's `animate` arrays; the flight is identical and the
+ * dependency is not needed.
+ *
+ * Under reduced motion nothing flies and `onDone` fires on the next tick, so
+ * whatever the flight was sequencing still completes.
+ *
+ * **Adds nothing where you write it.** Unlike the wrapping primitives here, the
+ * ghost renders into a portal and is positioned against the viewport, so mounting
+ * it never moves the layout it was written into — and it is free to fly across
+ * ancestors that clip or scroll.
+ *
+ * ```tsx
+ * {flight && (
+ *   <FlyTo from={flight.from} to={flight.to} onDone={clearFlight}>
+ *     <RewardChip credit={flight.reward} />
+ *   </FlyTo>
+ * )}
+ * ```
+ */
+export const FlyTo = forwardRef(
+  (
+    { from, to, lift = 46, onDone, children, css, ...rest }: FlyToProps,
+    ref?: ForwardedRef<HTMLDivElement>
+  ) => {
+    const reduced = useBreakpointValue(
+      { base: false, _motionReduce: true },
+      { ssr: false }
+    );
+
+    useEffect(() => {
+      if (reduced) onDone?.();
+      // `onDone` is intentionally absent from the deps: a caller that passes an
+      // inline arrow would otherwise fire the landing again on every parent
+      // render, and the landing is what advances the sequence.
+    }, [reduced]);
+
+    if (reduced) return null;
+
+    // Centre to centre. Corner to corner would land a chip that is wider than
+    // its target visibly off to one side.
+    const dx = to.left + to.width / 2 - (from.left + from.width / 2);
+    const dy = to.top + to.height / 2 - (from.top + from.height / 2);
+
+    return (
+      <Portal>
+        <Box
+          ref={ref}
+          left={`${from.left}px`}
+          top={`${from.top}px`}
+          {...rest}
+          css={[
+            flyGhost,
+            {
+              '--fly-dx': `${Math.round(dx)}px`,
+              '--fly-dy': `${Math.round(dy)}px`,
+              '--fly-lift': `${lift}px`,
+            },
+            css,
+          ]}
+          onAnimationEnd={onDone}
+        >
+          {children}
+        </Box>
+      </Portal>
+    );
+  }
+);
+
+FlyTo.displayName = 'FlyTo';

package/src/components/FlyTo/FlyTo.types.ts

@@ -0,0 +1,15 @@
+import type { BoxProps } from '@chakra-ui/react';
+
+export interface FlyToProps extends BoxProps {
+  /** Source rect in viewport coordinates, e.g. `el.getBoundingClientRect()`. */
+  from: DOMRect;
+  /** Target rect in viewport coordinates. */
+  to: DOMRect;
+  /**
+   * How high the arc rises above the straight line between the two rects.
+   * Defaults to 46px — enough to read as flight over a card-sized gap.
+   */
+  lift?: number;
+  /** Called once the ghost lands, or immediately under reduced motion. */
+  onDone?: () => void;
+}

package/src/components/FlyTo/index.ts

@@ -0,0 +1,2 @@
+export { FlyTo } from './FlyTo';
+export type { FlyToProps } from './FlyTo.types';

package/src/components/Form/FieldError/FieldError.test.tsx

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { FieldError } from './FieldError';
+
+// Field.ErrorText needs a Field.Root + invalid context to render; stub it to a
+// passthrough so the test isolates FieldError's own null-when-empty guard.
+vi.mock('@chakra-ui/react', () => ({
+  Field: {
+    ErrorText: ({ children }: { children?: ReactNode }) => (
+      <span data-testid="error-text">{children}</span>
+    ),
+  },
+}));
+
+describe('FieldError', () => {
+  it('renders nothing when empty (safe to mount unconditionally)', () => {
+    const { rerender } = render(<FieldError />);
+    expect(screen.queryByTestId('error-text')).toBeNull();
+
+    rerender(<FieldError>{''}</FieldError>);
+    expect(screen.queryByTestId('error-text')).toBeNull();
+
+    rerender(<FieldError>{false}</FieldError>);
+    expect(screen.queryByTestId('error-text')).toBeNull();
+  });
+
+  it('renders the message when present', () => {
+    render(<FieldError>Display name is required.</FieldError>);
+    expect(screen.getByText('Display name is required.')).toBeInTheDocument();
+  });
+});

package/src/components/Form/FieldError/FieldError.tsx

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+import { Field } from '@chakra-ui/react';
+
+export interface FieldErrorProps {
+  /** Error message. Renders nothing when empty, so it is safe to mount always. */
+  children?: ReactNode;
+}
+
+/**
+ * Field-level error message. Renders through Chakra's `Field.ErrorText`, so it
+ * shows only when the enclosing `FormControl`/`Field.Root` is `invalid`, and is
+ * wired to the control via `aria-describedby` + `aria-invalid` automatically.
+ * Use it inside a `FieldRow` (which flips the field to invalid when an `error`
+ * is set) — it replaces the hand-rolled `<Subtext color="danger.main">` error
+ * rows scattered across the app.
+ */
+export const FieldError = ({ children }: FieldErrorProps) => {
+  if (children == null || children === false || children === '') return null;
+  return <Field.ErrorText color="danger.main">{children}</Field.ErrorText>;
+};

package/src/components/Form/FieldError/index.ts

@@ -0,0 +1,2 @@
+export type { FieldErrorProps } from './FieldError';
+export { FieldError } from './FieldError';

package/src/components/Form/FieldHelp/FieldHelp.tsx

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+import { Field } from '@chakra-ui/react';
+
+export interface FieldHelpProps {
+  /** Helper text rendered under the control. */
+  children: ReactNode;
+}
+
+/**
+ * Inline helper text under a form control. Renders through Chakra's
+ * `Field.HelperText`, so it is associated with the control via
+ * `aria-describedby` when used inside a `FieldRow`/`FormControl`. For a hover
+ * info-popover instead of always-visible text, pass a logician `InfoSprinkle`
+ * into the `FieldRow` `endAdornment` slot.
+ */
+export const FieldHelp = ({ children }: FieldHelpProps) => {
+  return <Field.HelperText>{children}</Field.HelperText>;
+};

package/src/components/Form/FieldHelp/index.ts

@@ -0,0 +1,2 @@
+export type { FieldHelpProps } from './FieldHelp';
+export { FieldHelp } from './FieldHelp';

package/src/components/Form/FieldLabel/FieldLabel.tsx

@@ -0,0 +1,46 @@
+import { Box, Flex } from '@chakra-ui/react';
+
+import { FormLabel } from '@/components/FormLabel';
+import { Subtext } from '@/components/Typography';
+
+import { FieldLabelProps } from './FieldLabel.types';
+
+/**
+ * Label row for a form field: a semibold heading, an optional description, and
+ * an `endAdornment` slot on the right (count badge, action button, info-sprinkle
+ * trigger). The required asterisk is supplied automatically by the enclosing
+ * `Field` context when the field is `required` (see `FieldRow`).
+ *
+ * Presentational — pair it with `FieldRow` (or any logician `FormControl`) so
+ * the heading is programmatically associated with its control.
+ */
+export const FieldLabel = ({
+  heading,
+  description,
+  endAdornment,
+  mb = 0,
+  htmlFor,
+}: FieldLabelProps) => {
+  return (
+    <Flex align="center" justify="space-between" gap={2} mb={mb} w="100%">
+      <Box>
+        {heading != null && (
+          <FormLabel
+            mb={0}
+            fontWeight="semibold"
+            color="fg.default"
+            htmlFor={htmlFor}
+          >
+            {heading}
+          </FormLabel>
+        )}
+        {description && (
+          <Subtext fontWeight="normal" color="fg.muted">
+            {description}
+          </Subtext>
+        )}
+      </Box>
+      {endAdornment}
+    </Flex>
+  );
+};

package/src/components/Form/FieldLabel/FieldLabel.types.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+
+export interface FieldLabelProps {
+  /** Label heading. */
+  heading: ReactNode;
+  /** Secondary description rendered under the heading. */
+  description?: ReactNode;
+  /**
+   * Inline element rendered to the right of the heading row (e.g. button, count
+   * badge, info-sprinkle popover trigger).
+   */
+  endAdornment?: ReactNode;
+  /**
+   * Associates the label with a control by id. Normally supplied by the
+   * enclosing `Field` context (via `FieldRow`/`FormControl`); pass it explicitly
+   * only when using `FieldLabel` outside that context.
+   */
+  htmlFor?: string;
+  /** Bottom margin in spacing units. */
+  mb?: number;
+}

package/src/components/Form/FieldLabel/index.ts

@@ -0,0 +1,2 @@
+export { FieldLabel } from './FieldLabel';
+export type { FieldLabelProps } from './FieldLabel.types';

package/src/components/Form/FieldRow/FieldRow.stories.tsx

@@ -0,0 +1,85 @@
+import { Meta, StoryObj } from '@storybook/react';
+
+import { Input } from '@/components/Input';
+import { SelectField } from '@/components/Select';
+import { Textarea } from '@/components/Textarea';
+
+import { FieldRow } from './FieldRow';
+
+const meta: Meta<typeof FieldRow> = {
+  title: 'Components/Form/FieldRow',
+  component: FieldRow,
+  args: {
+    label: 'Display name',
+    children: <Input placeholder="Enter a name" />,
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The composition keystone for a form field. Wraps a control in a ' +
+          'logician `FormControl` and lays out label, description, helper and ' +
+          'error consistently, delegating all label↔control / aria wiring to ' +
+          'the Chakra `Field` context.',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof FieldRow>;
+
+export const Default: Story = {};
+
+export const Required: Story = {
+  args: { required: true },
+};
+
+export const WithDescription: Story = {
+  args: { description: 'Shown to teammates who can see this chatbot.' },
+};
+
+export const WithHelperText: Story = {
+  args: { helperText: 'Up to 40 characters.' },
+};
+
+export const WithError: Story = {
+  args: { required: true, error: 'Display name is required.' },
+};
+
+export const WithEndAdornment: Story = {
+  args: {
+    label: 'Recommended questions',
+    endAdornment: '2 / 5',
+    children: <Input placeholder="Add a question" />,
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+export const TextareaControl: Story = {
+  args: {
+    label: 'System instructions',
+    helperText: 'Describe how the assistant should behave.',
+    children: <Textarea placeholder="You are a helpful assistant…" />,
+  },
+};
+
+export const SelectControl: Story = {
+  args: {
+    label: 'Aspect ratio',
+    children: (
+      <SelectField
+        options={[
+          { label: '16:9', value: '16:9' },
+          { label: '9:16', value: '9:16' },
+          { label: '1:1', value: '1:1' },
+        ]}
+        value="16:9"
+        onChange={() => {}}
+      />
+    ),
+  },
+};

package/src/components/Form/FieldRow/FieldRow.test.tsx

@@ -0,0 +1,89 @@
+import type { ReactNode } from 'react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { FieldRow } from './FieldRow';
+
+// Expose the `invalid` value FieldRow computes onto the DOM so the derivation
+// (error -> invalid, with an explicit `invalid` override winning) is assertable
+// without a full Chakra Field/provider render. FieldRow now composes its label
+// out of the design system's own FormControl/FormLabel/Typography modules, so
+// mock those directly.
+vi.mock('@/components/FormControl', () => ({
+  FormControl: ({
+    children,
+    invalid,
+  }: {
+    children?: ReactNode;
+    invalid?: boolean;
+  }) => <div data-invalid={String(Boolean(invalid))}>{children}</div>,
+}));
+
+vi.mock('@/components/FormLabel', () => ({
+  FormLabel: ({ children }: { children?: ReactNode }) => (
+    <label>{children}</label>
+  ),
+}));
+
+vi.mock('@/components/Typography', () => ({
+  Subtext: ({ children }: { children?: ReactNode }) => <span>{children}</span>,
+}));
+
+vi.mock('@chakra-ui/react', () => ({
+  Box: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
+  Flex: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
+  Field: {
+    HelperText: ({ children }: { children?: ReactNode }) => (
+      <p data-testid="helper">{children}</p>
+    ),
+    ErrorText: ({ children }: { children?: ReactNode }) => (
+      <p data-testid="error">{children}</p>
+    ),
+  },
+}));
+
+const control = <input aria-label="name" />;
+
+describe('FieldRow', () => {
+  it('renders label, control, helper and error slots', () => {
+    render(
+      <FieldRow label="Display name" helperText="Up to 40 chars" error="Nope">
+        {control}
+      </FieldRow>
+    );
+    expect(screen.getByText('Display name')).toBeInTheDocument();
+    expect(screen.getByLabelText('name')).toBeInTheDocument();
+    expect(screen.getByTestId('helper')).toHaveTextContent('Up to 40 chars');
+    expect(screen.getByTestId('error')).toHaveTextContent('Nope');
+  });
+
+  it('flips the field to invalid when an error is set', () => {
+    const { container } = render(
+      <FieldRow label="Name" error="Required">
+        {control}
+      </FieldRow>
+    );
+    expect(container.querySelector('[data-invalid="true"]')).not.toBeNull();
+  });
+
+  it('is not invalid without an error', () => {
+    const { container } = render(<FieldRow label="Name">{control}</FieldRow>);
+    expect(container.querySelector('[data-invalid="false"]')).not.toBeNull();
+    expect(screen.queryByTestId('error')).toBeNull();
+  });
+
+  it('lets an explicit invalid prop win over the error-derived value', () => {
+    const { container } = render(
+      <FieldRow label="Name" error="Required" invalid={false}>
+        {control}
+      </FieldRow>
+    );
+    expect(container.querySelector('[data-invalid="false"]')).not.toBeNull();
+  });
+
+  it('omits the label row when there is no label or adornment', () => {
+    const { container } = render(<FieldRow>{control}</FieldRow>);
+    expect(container.querySelector('label')).toBeNull();
+    expect(screen.getByLabelText('name')).toBeInTheDocument();
+  });
+});

package/src/components/Form/FieldRow/FieldRow.tsx

@@ -0,0 +1,46 @@
+import { FormControl } from '@/components/FormControl';
+
+import { FieldError } from '../FieldError';
+import { FieldHelp } from '../FieldHelp';
+import { FieldLabel } from '../FieldLabel';
+import { FieldRowProps } from './FieldRow.types';
+
+/**
+ * The composition keystone for a form field: wraps a control in a logician
+ * `FormControl` (Chakra `Field.Root`) and lays out its label, optional
+ * description/help, and error consistently. Because it delegates to the `Field`
+ * context, the label↔control association, the `required` asterisk, `aria-invalid`
+ * and the error/helper `aria-describedby` wiring are all handled automatically —
+ * callers never thread ids by hand.
+ *
+ * It is form-library agnostic: pass `value`/`onChange` controls directly (media
+ * forms) or render a form-connected adapter as the child (studio/admin forms). Set
+ * `error` to flip the field to invalid and surface the message.
+ */
+export const FieldRow = ({
+  label,
+  description,
+  endAdornment,
+  helperText,
+  error,
+  invalid,
+  children,
+  labelProps,
+  ...rootProps
+}: FieldRowProps) => {
+  return (
+    <FormControl invalid={invalid ?? Boolean(error)} {...rootProps}>
+      {(label != null || endAdornment != null) && (
+        <FieldLabel
+          heading={label}
+          description={description}
+          endAdornment={endAdornment}
+          {...labelProps}
+        />
+      )}
+      {children}
+      {helperText != null && <FieldHelp>{helperText}</FieldHelp>}
+      <FieldError>{error}</FieldError>
+    </FormControl>
+  );
+};