@godxjp/ui 28.6.0 → 28.8.0

package/dist/lib/hooks.js

@@ -1,4 +1,5 @@
 "use client";
+import { useLayoutEffect } from "@react-aria/utils";
 import { useEffect, useState } from "react";
 function useDebouncedValue(value, delay = 250) {
   const [debounced, setDebounced] = useState(value);
@@ -104,11 +105,89 @@ function useScrollableRegionTabIndex(element) {
     };
   }, [element]);
 }
+function useScrollsOnAxis(ref, enabled, axis) {
+  const [scrolls, setScrolls] = useState(true);
+  useEffect(() => {
+    const el = ref.current;
+    if (!enabled || !el) return void 0;
+    const overflows = (client, scroll) => client === 0 || scroll - client > 1;
+    const update = () => {
+      setScrolls(
+        axis !== "vertical" && overflows(el.clientWidth, el.scrollWidth) || axis !== "horizontal" && overflows(el.clientHeight, el.scrollHeight)
+      );
+    };
+    update();
+    if (typeof ResizeObserver === "undefined") return void 0;
+    const observer = new ResizeObserver(update);
+    observer.observe(el);
+    if (el.firstElementChild) observer.observe(el.firstElementChild);
+    return () => {
+      observer.disconnect();
+    };
+  }, [ref, enabled, axis]);
+  return enabled && scrolls;
+}
+function useScrollsHorizontally(ref, enabled) {
+  return useScrollsOnAxis(ref, enabled, "horizontal");
+}
+function scrollParent(el) {
+  let node = el?.parentElement ?? null;
+  while (node) {
+    const overflowY = getComputedStyle(node).overflowY;
+    if (overflowY === "auto" || overflowY === "scroll" || overflowY === "overlay") return node;
+    node = node.parentElement;
+  }
+  return null;
+}
+function useInView(ref, {
+  enabled = true,
+  once = false,
+  amount = "some",
+  root = null,
+  rootMargin,
+  assumeInView = false
+} = {}) {
+  const [inView, setInView] = useState(true);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!enabled || !el || typeof IntersectionObserver === "undefined") return void 0;
+    const requested = typeof amount === "number" ? amount : amount === "all" ? 1 : 0;
+    const box = el.getBoundingClientRect();
+    const rootBox = root?.getBoundingClientRect();
+    const rootWidth = rootBox?.width ?? window.innerWidth;
+    const rootHeight = rootBox?.height ?? window.innerHeight;
+    const reachable = box.width > 0 && box.height > 0 ? Math.min(box.width, rootWidth) * Math.min(box.height, rootHeight) / (box.width * box.height) : 1;
+    const threshold = Math.min(requested, reachable);
+    if (!assumeInView) setInView(false);
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[entries.length - 1];
+        if (!entry) return;
+        if (entry.isIntersecting && entry.intersectionRatio >= threshold) {
+          setInView(true);
+          if (once) observer.unobserve(entry.target);
+        } else if (!once) {
+          setInView(false);
+        }
+      },
+      { root, threshold, ...rootMargin === void 0 ? void 0 : { rootMargin } }
+    );
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+    };
+  }, [ref, enabled, once, amount, root, rootMargin, assumeInView]);
+  return !enabled || inView;
+}
 export {
+  scrollParent,
   useControlledLatch,
   useDebouncedValue,
+  useInView,
   useIsMobile,
   useMediaQuery,
   useScrollableRegionTabIndex,
+  useScrollsHorizontally,
+  useScrollsOnAxis,
   useTimeoutFlag
 };

package/dist/lib/platform.d.ts

@@ -8,3 +8,17 @@
  * server render therefore describes the Ctrl shortcut.
  */
 export declare function isApplePlatform(): boolean;
+/**
+ * Has the user asked for reduced motion (WCAG 2.3.3)?
+ *
+ * Read at the moment of the gesture rather than subscribed to, because every caller asks the same
+ * question at the same instant: "am I allowed to tween THIS scroll / THIS transition". A falsy or
+ * unsupported environment — SSR, jsdom, a browser without `matchMedia`, a `matchMedia` that throws
+ * on an unknown feature — answers `false`, which is the ordinary animated behaviour rather than a
+ * crash.
+ *
+ * It lives here rather than beside its first caller because it had already been written twice
+ * (`src/form/form-root.tsx`, `src/components/layout/legal-document-shell.tsx`) before a third
+ * caller needed it.
+ */
+export declare function prefersReducedMotion(): boolean;

package/dist/lib/platform.js

@@ -4,6 +4,15 @@ function isApplePlatform() {
   const platform = data?.platform || navigator.platform || "";
   return /mac|iphone|ipad|ipod/i.test(platform);
 }
+function prefersReducedMotion() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  try {
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  } catch {
+    return false;
+  }
+}
 export {
-  isApplePlatform
+  isApplePlatform,
+  prefersReducedMotion
 };

package/dist/lib/utils.d.ts

@@ -1,3 +1,3 @@
 import { type ClassValue } from "clsx";
 export declare function cn(...inputs: ClassValue[]): string;
-export { isApplePlatform } from "./platform.js";
+export { isApplePlatform, prefersReducedMotion } from "./platform.js";

package/dist/lib/utils.js

@@ -3,8 +3,9 @@ import { twMerge } from "tailwind-merge";
 function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
-import { isApplePlatform } from "./platform.js";
+import { isApplePlatform, prefersReducedMotion } from "./platform.js";
 export {
   cn,
-  isApplePlatform
+  isApplePlatform,
+  prefersReducedMotion
 };

package/dist/props/components/data-display.prop.d.ts

@@ -36,7 +36,7 @@ export type ProseProp = {
     className?: ClassNameProp;
     children?: ChildrenProp;
 };
-import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, GetRowLabelProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, TablePresetProp, BreakpointProp, DensityProp, ChildrenProp, PendingProp, ToneProp, AvatarShapeProp, HeadingLevelProp, HandlerProp, SizeProp, LabelProp, IdProp, DescriptionsLayoutProp, DescriptionsColumnProp, DescriptionsSpanProp, DescriptionsItemsProp, SortDirectionProp, OnColumnFilterChangeProp, OnRowProp, TableExpandableProp, TableRowSelectionProp, TableScrollProp, TableStickyProp, TableSummaryProp, DisabledProp, OnClickProp, ValueProp, DefaultValueProp, OnValueChangeProp } from "../vocabulary/index.js";
+import type { ActionProp, ClassNameProp, DescriptionProp, IconProp, TitleProp, ColumnDefProp, GetRowIdProp, GetRowLabelProp, OnRowClickProp, OnSelectChangeProp, OnSortChangeProp, OnTableDensityChangeProp, SelectedIdsProp, SortStateProp, TableDensityProp, TablePresetProp, BreakpointProp, DensityProp, ChildrenProp, PendingProp, ToneProp, AvatarShapeProp, HeadingLevelProp, HandlerProp, SizeProp, LabelProp, IdProp, DescriptionsLayoutProp, DescriptionsColumnProp, DescriptionsSpanProp, DescriptionsItemsProp, GapProp, SortDirectionProp, OnColumnFilterChangeProp, OnRowProp, TableExpandableProp, TableRowSelectionProp, TableScrollProp, TableStickyProp, TableSummaryProp, DisabledProp, OnClickProp, ValueProp, DefaultValueProp, OnValueChangeProp } from "../vocabulary/index.js";
 import type { TreeFieldNamesProp, TreeOptionProp } from "./data-entry.prop.js";
 /**
  * One key in a `Legend`: a tone, and the words that tone stands for.
@@ -605,6 +605,20 @@ export type ScrollAreaProp = {
      * from it — anchoring must never be the only route back to new content.
      */
     onAnchoredChange?: (anchored: boolean) => void;
+    /**
+     * Accessible name for the scroll REGION — the `tabindex="0"` element a keyboard user lands on to
+     * scroll content taller or wider than the box.
+     *
+     * Optional on purpose. A consumer is never forced to invent a name for every scrolling box: left
+     * out, the region takes the localized `dataDisplay.scrollArea.region` default ("Scrollable
+     * region"), which is what a screen-reader user needs to hear anyway — that the arrow keys now
+     * scroll something. Pass a plain string when the screen can say WHICH region ("Activity log"); a
+     * non-string node cannot be an `aria-label`, so it falls back to the default.
+     *
+     * The region is only announced while it HAS overflow to reach, on the axes `orientation` opens:
+     * no overflow, no tab stop, no role and no name. (gh#821)
+     */
+    label?: LabelProp;
 };
 /**
  * @see TimelineGrid — one COLUMN of the grid (a day, a room, a machine). The label names the
@@ -1018,3 +1032,97 @@ export type CardTabItemProp = {
     /** Ant Design `closeIcon` — replaces the default × on this tab's remove button. */
     closeIcon?: React.ReactNode;
 };
+/**
+ * @see Marquee — direction of travel, spelled LOGICALLY.
+ *
+ * `react-fast-marquee` says `left | right`; this says `start | end`, the edge the content travels
+ * TOWARDS. `start` is the default because it is the one that follows the reading direction: the
+ * next item arrives from the end edge, exactly as the next word does. Under `dir="rtl"` both
+ * members mirror with the text, so an Arabic page's default marquee travels rightwards with no
+ * prop change at the call site.
+ *
+ * The vertical members of the prior art (`up` / `down`) are NOT ported. A vertical ticker fights
+ * the page scroll and has a different failure mode; porting an axis nobody asked for is how a
+ * single-responsibility component stops being one.
+ */
+export type MarqueeDirectionProp = "start" | "end";
+/**
+ * @see Marquee — travel pace, as an ordinal over the `--marquee-interval` motion token rather than
+ * the prior art's raw `speed` in px/s.
+ *
+ * A px/s number is neither themeable nor width-aware: 50px/s reads as a crawl on a 2560px display
+ * and a sprint on a 390px phone. The ordinal resolves to a duration per SCREENFUL, so the
+ * perceived pace is the same at every width, and a service retunes all of them from one token.
+ */
+export type MarqueeSpeedProp = "slow" | "base" | "fast";
+/**
+ * @see Marquee — a track of content that travels continuously, carrying the WCAG 2.2.2 pause
+ * control that makes it conformant.
+ *
+ * The clone count is MEASURED (content width against viewport width, re-measured on resize) —
+ * the behaviour no CSS-only marquee can have — and the pause control is why this is a component
+ * rather than a snippet. See `src/components/data-display/marquee.tsx` for the full argument and
+ * for what is deliberately not ported from `react-fast-marquee`.
+ */
+export type MarqueeProp = Omit<React.HTMLAttributes<HTMLDivElement>, "onPlay" | "onPause" | "children"> & {
+    /**
+     * The row of content — logos, headlines, status chips. Rendered ONCE for real; every further
+     * copy that fills the track is an `aria-hidden` + `inert` clone, so the accessibility tree and
+     * the tab order see the content exactly once however wide the viewport is.
+     */
+    children?: ChildrenProp;
+    /**
+     * Whether the track is moving. The controlled member of the triad — pass it with
+     * `onPlayChange`.
+     *
+     * WCAG 2.2.2 is satisfied by the built-in control whichever way this is driven; a controlled
+     * `play` exists so one "stop all motion" switch can halt every marquee on a page at once.
+     */
+    play?: boolean;
+    /**
+     * Uncontrolled initial state. Default `true`.
+     *
+     * WebAIM recommends animated content be paused by default where the motion is not the point of
+     * the screen (https://webaim.org/techniques/carousels/); `defaultPlay={false}` is that screen,
+     * and it still starts from the built-in control.
+     */
+    defaultPlay?: boolean;
+    /** Fires on every transition, from the built-in control or from a controlled write. */
+    onPlayChange?: (play: boolean) => void;
+    /** Edge the content travels towards. Default `start` — the reading direction. */
+    direction?: MarqueeDirectionProp;
+    /** Pace ordinal over `--marquee-interval`. Default `base`. */
+    speed?: MarqueeSpeedProp;
+    /**
+     * Space between items AND between copies, as a token step. Defaults to the
+     * `--marquee-gap-inline` token, so a service sets the resting rhythm once.
+     */
+    gap?: GapProp;
+    /**
+     * Also pause while the pointer is over the track. Default `false`.
+     *
+     * An ADDITION, never the mechanism: a keyboard user never hovers, so hover-to-pause alone is
+     * exactly the WCAG 2.2.2 failure (technique F16) the prior art ships. Focus inside the track
+     * always pauses it, whatever this says, because a link that is moving cannot be activated.
+     */
+    pauseOnHover?: boolean;
+    /**
+     * Fade both edges over `--marquee-mask-width` so items enter and leave instead of being cut.
+     * Default `false`. A mask, not the prior art's opaque `gradientColor` — a gradient painted in a
+     * fixed colour cannot follow a themed or dark background.
+     */
+    fade?: boolean;
+    /**
+     * Names the CONTENT, not the button: "partner logos", "お知らせ". The control's accessible name
+     * is built from it ("Pause scrolling: partner logos"), so a page with several tracks can tell
+     * them apart by voice as well as by eye.
+     *
+     * It is not the whole button name on purpose. A caller string would read the same in both
+     * states, and a control that says "pause" while it resumes is worse than an unnamed one; the
+     * verb stays the component's, and the catalog composes the two in each locale's own order.
+     * Optional: omitted, the control takes the localized verb alone. A non-string node cannot be an
+     * `aria-label`, so it is ignored.
+     */
+    label?: LabelProp;
+    className?: ClassNameProp;
+};

package/dist/props/components/general.prop.d.ts

@@ -1,6 +1,6 @@
 /** Foundation component prop types — @see docs/COMPONENTS.md#foundation */
 import type * as React from "react";
-import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DescriptionProp, DisabledProp, FontWeightProp, HeadingLevelProp, IconSizeProp, IdProp, LabelProp, OnClickProp, OnOpenChangeProp, OpenProp, PendingProp, RevealDelayProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp, TextWhitespaceProp, TitleLevelProp, TypographyActionsConfigProp, TypographyCopyConfigProp, TypographyEditConfigProp, TypographyEllipsisConfigProp, TypographyTypeProp } from "../vocabulary/index.js";
+import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSizeProp, ButtonVariantProp, ChildrenProp, ClassNameProp, DescriptionProp, DisabledProp, FontWeightProp, HeadingLevelProp, IconSizeProp, IdProp, InViewAmountProp, LabelProp, OnClickProp, OnOpenChangeProp, OpenProp, PendingProp, RevealDelayProp, RevealTriggerProp, ShapeProp, SizeProp, TextAlignProp, TextSizeProp, TextToneProp, TextWhitespaceProp, TitleLevelProp, TypographyActionsConfigProp, TypographyCopyConfigProp, TypographyEditConfigProp, TypographyEllipsisConfigProp, TypographyTypeProp } from "../vocabulary/index.js";
 /**
  * @see Text — typographic primitive; replaces hand-rolled `<span className="text-[13px] …">`.
  *
@@ -87,10 +87,24 @@ export type TextProp = Omit<React.HTMLAttributes<HTMLElement>, "color"> & Omit<T
     rel?: string;
     download?: React.AnchorHTMLAttributes<HTMLAnchorElement>["download"];
 };
-/** @see Heading — h1..h4 sized from the `--heading-h*` tokens. */
+/** @see Heading — h1..h4 sized from the `--heading-h*` tokens, or from `size` when one is given. */
 export type HeadingProp = Omit<React.HTMLAttributes<HTMLHeadingElement>, "color"> & {
     /** Heading level — sets size token AND the semantic element (override the element with `as`). */
     level?: HeadingLevelProp;
+    /**
+     * Visual size, overriding the step `level` would have taken — the SAME ten-step ladder
+     * `Text size` reads, so a headline and a stat figure beside it are one step name apart rather
+     * than a lookup between two ramps.
+     *
+     * `level` still owns the document outline, and that separation is the point (gh#826). The
+     * enterprise heading ramp tops out at `--heading-h1` ≈ 20px by deliberate 渋み restraint, so a
+     * marketing hero had no way to be both a real `<h1>` and 54px: the display tokens existed,
+     * nothing public reached them, and every marketing page wrote its own class instead. Now it is
+     * `<Heading level={1} size="5xl">`, and no admin screen's `<h1>` moves.
+     *
+     * Omit it and `level` decides, exactly as before — this is an override, not a second default.
+     */
+    size?: TextSizeProp;
     as?: "h1" | "h2" | "h3" | "h4" | "div";
     tone?: TextToneProp;
     align?: TextAlignProp;
@@ -284,10 +298,20 @@ export type ButtonProp = React.ButtonHTMLAttributes<HTMLButtonElement> & {
 };
 /**
  * @see Reveal — entrance-motion primitive (staggered fade-up). Wraps content in a real element
- * that animates in on mount reading the DS motion tokens (`--duration-slow`, `--ease-emphasized`,
+ * that animates in reading the DS motion tokens (`--duration-slow`, `--ease-emphasized`,
  * `--reveal-distance`), replacing hand-rolled `@keyframes` + `.app-reveal`/`.d1..d6` classes.
  * Honours `prefers-reduced-motion` — the animation is dropped and content stays fully visible with
  * no layout shift.
+ *
+ * `on` moves the TRIGGER and nothing else (gh#829): `"mount"` is the historical behaviour, `"view"`
+ * waits for the viewport. There is deliberately no second `ScrollReveal` component — same
+ * animation, same tokens, same reduced-motion contract, one extra prop.
+ *
+ * **Visibility is never gated on the observer.** The resting state in the stylesheet is the FINAL,
+ * fully visible one; only a mounted component that has attached a live `IntersectionObserver` and
+ * measured the element as still outside the viewport writes the hidden state. A server render,
+ * jsdom, a browser without `IntersectionObserver` and `prefers-reduced-motion: reduce` therefore
+ * all show the content — a reveal that never reveals is the worst outcome available here.
  */
 export type RevealProp = React.HTMLAttributes<HTMLDivElement> & {
     /** Child content to reveal on enter. */
@@ -297,6 +321,26 @@ export type RevealProp = React.HTMLAttributes<HTMLDivElement> & {
      * `--reveal-stagger-step` of delay so sibling reveals cascade.
      */
     delay?: RevealDelayProp;
+    /**
+     * What starts the entrance. Default `"mount"` — today's behaviour, so nothing moves for existing
+     * consumers. `"view"` holds the entrance until the element reaches the viewport.
+     */
+    on?: RevealTriggerProp;
+    /**
+     * `on="view"` only. Reveal once and never re-hide. Default `true` — a `Reveal` is a ONE-SHOT
+     * entrance under either trigger, so this keeps `"view"` semantically identical to `"mount"`.
+     * (Motion's `useInView`, where this prop comes from, defaults it to `false`; that is the neutral
+     * reading for a general-purpose observer, not for an entrance primitive.) `false` re-plays the
+     * entrance on every re-entry.
+     */
+    once?: boolean;
+    /**
+     * `on="view"` only. How much of the element must be visible before it reveals — Motion's
+     * `amount`, unchanged: `"some"` (default, any pixel) | `"all"` | an explicit `0..1` ratio.
+     * `"all"` is clamped to the most the element's own box can show inside the viewport, so a
+     * full-height section still reveals.
+     */
+    amount?: InViewAmountProp;
     /**
      * Merge the reveal behaviour onto the single child element (Radix `Slot`) instead of rendering a
      * wrapper `<div>` — use when an extra box would break a grid/flex layout. Default `false`.

package/dist/props/components/layout.prop.d.ts

@@ -1657,3 +1657,197 @@ export type DraggablePanelProp = Omit<React.HTMLAttributes<HTMLElement>, "title"
     disabled?: DisabledProp;
     className?: ClassNameProp;
 };
+/**
+ * Masonry column count — Ant Design `Masonry columns`, in this library's responsive shape.
+ *
+ * A plain number is that many columns at every width. The object form is the step map
+ * `Flex direction` already uses — `base` plus `sm` 40rem · `md` 48rem · `lg` 64rem · `xl` 80rem —
+ * and each omitted step falls back to the widest one below it, exactly as the `--flex-direction-*`
+ * cascade does in CSS.
+ *
+ * **antd spells the steps `xs sm md lg xl xxl` and this does not.** The two ends are the
+ * divergence: antd's `xs` is its mobile-first floor, which is this library's `base` (a second
+ * spelling of one axis is what `check:prop-vocabulary` exists to prevent), and `xxl` has no step
+ * here at all. An `xs` or `xxl` key is therefore never silently dropped — TypeScript rejects it as
+ * an excess property, and a value that reaches the component anyway (a plain-JS caller, a widened
+ * object) is named in a development-only warning. See docs/DESIGN-AUTHORITY.md.
+ * @see Masonry
+ */
+export type MasonryColumnsProp = number | Partial<Record<"base" | BreakpointProp, number>>;
+/**
+ * Masonry spacing — Ant Design `Masonry gutter`, on this library's `GapProp` scale.
+ *
+ * One step applies to both axes; the tuple is antd's `[Gap, Gap]`, i.e. `[inline, block]`.
+ * The value is a TOKEN STEP rather than antd's raw pixel number, so a masonry breathes with
+ * `--scaling` (density) like every other gap in the package.
+ * @see Masonry
+ */
+export type MasonryGapProp = GapProp | [GapProp, GapProp];
+/**
+ * One tile handed to `Masonry items` — Ant Design `MasonryItem`, field for field.
+ * @see Masonry
+ */
+export type MasonryItemProp<TData = unknown> = {
+    /** Identity of the tile across re-orders and re-measures. Ant Design `MasonryItem.key`. */
+    key: React.Key;
+    /** The tile itself. Wins over `itemRender`, as in Ant Design. */
+    children?: ReactNode;
+    /**
+     * Pin the tile to a column INDEX (0-based) instead of letting it fall into the shortest one.
+     * Ant Design `MasonryItem.column`, clamped to the live column count.
+     */
+    column?: number;
+    /**
+     * Declared block size, in pixels, used INSTEAD of measuring the tile.
+     *
+     * antd declares and documents this field and then never reads it — its layout is measured from
+     * `getBoundingClientRect()` alone, and all six of its demos carry their heights in `data`. A
+     * prop that does nothing is worse than an absent one, so here the documented meaning is the
+     * real one: a finite `height` sizes the tile and skips its measurement, which is what makes a
+     * first paint (and an SSR render) land in the right place.
+     */
+    height?: number;
+    /** Arbitrary payload handed back to `itemRender` and `onLayoutChange`. Ant Design `MasonryItem.data`. */
+    data?: TData;
+};
+/** One row of the `onLayoutChange` payload: the item, plus the column it landed in. @see Masonry */
+export type MasonryLayoutEntryProp<TData = unknown> = MasonryItemProp<TData> & {
+    /** 0-based column index the item occupies. */
+    column: number;
+};
+/**
+ * @see Masonry — Ant Design's `Masonry` (6.0.0): tiles of unequal height packed into columns.
+ *
+ * Ant's own surface, field for field: `items`, `itemRender`, `columns`, `fresh`, `onLayoutChange`.
+ * The three named divergences (`gap` for `gutter`, the breakpoint step names, and the absence of
+ * `classNames`/`styles`) each carry their reason at the field, and all three are recorded in
+ * docs/DESIGN-AUTHORITY.md.
+ */
+export type MasonryProp<TData = unknown> = {
+    /** The tiles, in READING order — which is also DOM order. Ant Design `items`. */
+    items?: MasonryItemProp<TData>[];
+    /**
+     * Renders a tile that carries no `children`. Receives the item plus its live `index` and
+     * `column`, exactly as Ant Design does. Ant Design `itemRender`.
+     */
+    itemRender?: (item: MasonryItemProp<TData> & {
+        index: number;
+        column: number;
+    }) => ReactNode;
+    /** Column count, fixed or per step. Ant Design `columns`, default `3`. */
+    columns?: MasonryColumnsProp;
+    /**
+     * Spacing between tiles, on the `GapProp` scale. Ant Design calls this `gutter` and defaults it
+     * to `0`; the name here is `gap` because this package already owns that axis under that name
+     * (`Flex`, `ResponsiveGrid`, `AuthStack`, …) and `check:prop-vocabulary` maps a field called
+     * `gap` to `GapProp`. The antd default is kept: omitted means `"none"`.
+     */
+    gap?: MasonryGapProp;
+    /**
+     * NOT A PROP — Ant Design's name for `gap`, kept in the type so that arriving from antd's docs
+     * is a compile error that says where to go, rather than a tile grid with no spacing and no
+     * complaint. Passing it also warns in development.
+     *
+     * @deprecated Ant Design spells this `gutter`; in `@godxjp/ui` it is `gap`, and it takes a
+     * `GapProp` token step (`"sm"`, `4`, `["md", "lg"]`) rather than antd's raw pixel number.
+     */
+    gutter?: never;
+    /**
+     * Keep watching every tile's own size, not just the container's.
+     *
+     * Ant Design `fresh`, and it means exactly one thing in Ant's source: each tile is wrapped in
+     * its own `ResizeObserver` so a tile that changes height on its own — an image decoding, a
+     * "show more" expanding, a chart settling — re-packs the columns. Off (the default), the layout
+     * is re-measured only when the CONTAINER resizes or a descendant `load`/`error` event fires, so
+     * a tile that grows in place leaves a gap or overlaps its neighbour until something else moves.
+     */
+    fresh?: boolean;
+    /**
+     * Fires when the column assignment changes. Ant Design `onLayoutChange`.
+     *
+     * Ant's own documented type is `({ key, column }[]) => void`, but its implementation hands back
+     * the WHOLE item spread with `column` added — so `data` and `children` come with it. This ports
+     * the implementation (a superset of the documented payload) rather than the narrower doc.
+     *
+     * It fires only once every tile has a resolved position and the count matches `items`, and is
+     * deduped: an identical [item, column] list does not call it again.
+     */
+    onLayoutChange?: (layout: MasonryLayoutEntryProp<TData>[]) => void;
+    id?: IdProp;
+    className?: ClassNameProp;
+};
+/**
+ * The scroll box an `Affix` pins against — Ant Design `Affix target`, shape for shape, and the
+ * same lazy getter `FloatButton.BackTop target` already spells here.
+ *
+ * It is a FUNCTION and not an element because the element does not exist on the render that
+ * declares it: the caller writes `target={() => scrollRef.current}` and the component calls it
+ * after mount. `window` (the default) means the document viewport.
+ * @see Affix
+ */
+export type AffixTargetProp = () => Window | HTMLElement | null;
+/**
+ * @see Affix — Ant Design's `Affix`: pin an element to its scrollport once the page scrolls past
+ * it, and SAY SO, which is the whole difference from `position: sticky`.
+ *
+ * antd's surface, field for field — `offsetTop`, `offsetBottom`, `target`, `onChange` — with the
+ * two physical offsets renamed to their logical axis (see the fields). `onChange` keeps antd's
+ * name and antd's payload: it is an OBSERVATION of a derived boolean, not the setter half of a
+ * controlled value, so the `value`/`defaultValue`/`onValueChange` triad does not apply to it —
+ * the same call `Attachments.onChange` and `ActionsFeedback.onChange` already make here.
+ */
+export type AffixProp = {
+    /** What gets pinned. Must not itself be `position: absolute` — antd's note, and it is the same
+     * note here, because the pin works by making this element `position: fixed`. */
+    children?: ChildrenProp;
+    /**
+     * Distance from the scrollport's BLOCK-START edge at which the element pins, in pixels.
+     * Ant Design `offsetTop`, default `0`.
+     *
+     * The name is the logical axis, not `top`, for the reason `check:rtl` exists and the reason
+     * `inset-block-start` replaced `top` in every stylesheet here: a sticky bar in a
+     * `writing-mode: vertical-rl` document pins against the axis it flows on, and "top" is only
+     * the right word for one of the four. `offsetTop` is still FINDABLE — it is declared `never`
+     * below, so arriving from antd's docs is a compile error that names the replacement.
+     *
+     * Pass neither offset and this defaults to `0` (antd's `internalOffsetTop` rule exactly:
+     * the block-start offset defaults to `0` ONLY when the block-end offset is also absent).
+     */
+    offsetBlockStart?: number;
+    /**
+     * Distance from the scrollport's BLOCK-END edge at which the element pins, in pixels.
+     * Ant Design `offsetBottom`. No default — passing it is what selects block-end pinning.
+     *
+     * Setting both is antd's own precedence: block-start wins, and block-end is only consulted
+     * when the element has not pinned to the start.
+     */
+    offsetBlockEnd?: number;
+    /**
+     * NOT A PROP — Ant Design's name for `offsetBlockStart`, kept in the type so that arriving from
+     * antd's docs is a compile error that says where to go, rather than a header that never pins
+     * and never complains. Passing it also warns in development.
+     *
+     * @deprecated Ant Design spells this `offsetTop`; in `@godxjp/ui` it is `offsetBlockStart` —
+     * the logical axis, per `check:rtl` and docs/DESIGN-AUTHORITY.md.
+     */
+    offsetTop?: never;
+    /**
+     * NOT A PROP — Ant Design's name for `offsetBlockEnd`. See `offsetTop`.
+     *
+     * @deprecated Ant Design spells this `offsetBottom`; in `@godxjp/ui` it is `offsetBlockEnd`.
+     */
+    offsetBottom?: never;
+    /** The scroll box to pin against. Ant Design `target`, default `() => window`. */
+    target?: AffixTargetProp;
+    /**
+     * Fires when the pinned state FLIPS, and only then — never on a scroll frame that did not
+     * change it. Ant Design `onChange`, whose payload is the new state.
+     *
+     * antd types the argument optional (`(affixed?: boolean) => void`) because its own call site can
+     * pass `undefined`; here the transition is derived from a boolean, so the argument is always
+     * present and the type says so. A handler written against antd's signature still compiles.
+     */
+    onChange?: (affixed: boolean) => void;
+    id?: IdProp;
+    className?: ClassNameProp;
+};