@stonedogcode/style 0.19.0 → 0.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "A Panda CSS design system: a themeable Panda preset plus the React components built on it.",
   "license": "Apache-2.0",
   "author": "StoneDogCode L.L.C.",

package/src/components/StyledImageUpload.tsx

@@ -0,0 +1,387 @@
+"use client";
+
+import React from "react";
+import { styled, type HTMLStyledProps } from "styled-system/jsx";
+import { log } from "../config/logger";
+import StyledButton from "./StyledButton";
+import StyledText from "./StyledText";
+
+/**
+ * A file dropzone with image previews.
+ *
+ * Extracted from HopperGuard, where it replaced Chakra's `FileUpload` compound
+ * component. Chakra supplied Root/HiddenInput/Dropzone/Trigger/ItemGroup/Item/
+ * ItemPreviewImage/ItemDeleteTrigger plus `useFileUploadContext`; all of it is
+ * reconstructed here on a local context, because the pieces share state (the
+ * accepted files) and cannot be swapped one at a time.
+ *
+ * ## What must not be lost
+ *
+ * These are pinned by the originating app's e2e spec, and each one is easy to
+ * break while the component still looks right:
+ *
+ *   - a real `<input type="file">` stays ATTACHED to the DOM
+ *   - the dropzone is reachable and operable BY KEYBOARD — so the trigger is a
+ *     real `<button>`, never a div with a click handler
+ *   - the dropzone announces itself IN WORDS, not by icon alone
+ *   - selecting a file does not tear the widget down
+ *
+ * ## Icons
+ *
+ * This package ships no artwork by policy (see `StyledAlert`), so both glyph
+ * slots default to nothing and the words carry the meaning on their own. Pass
+ * your own nodes to restore an icon set — HopperGuard's facade passes
+ * `react-icons`' `LuFileImage` and `LuX`, which is what it rendered before the
+ * extraction.
+ */
+
+interface FileUploadContextValue {
+  acceptedFiles: File[];
+  openPicker: () => void;
+  removeFile: (file: File) => void;
+}
+
+const FileUploadContext = React.createContext<FileUploadContextValue | null>(
+  null,
+);
+
+function useFileUploadContext(): FileUploadContextValue {
+  const ctx = React.useContext(FileUploadContext);
+  if (!ctx) {
+    throw new Error(
+      "useFileUploadContext must be used inside StyledImageUpload",
+    );
+  }
+  return ctx;
+}
+
+const PandaVStack = styled("div", {
+  base: { display: "flex", flexDirection: "column", alignItems: "center" },
+});
+const PandaItemGroup = styled("div", {
+  base: {
+    display: "flex",
+    flexWrap: "wrap",
+    gap: "2",
+    justifyContent: "center",
+  },
+});
+const PandaItem = styled("div", { base: { position: "relative" } });
+
+/**
+ * Chakra's `Float` — the delete control at the item's top-end corner.
+ *
+ * The `translate(40%, -40%)` this used to carry is gone (NEH-1117). It centred
+ * the control ON the corner, so roughly half of it hung outside the preview it
+ * belonged to — measured in Chromium at every viewport, the control's top edge
+ * sat at **y = -7.2**, above the top of the page. That is tolerable while the
+ * control is 16px and merely untidy; at the 48px hit area below it would put
+ * two neighbouring previews' targets into the same few pixels, which is the
+ * sharper half of what the issue reports.
+ *
+ * So the hit area is anchored inside the tile instead, and the visible chip
+ * sits in its top-end corner — which lands the chip in very nearly the place
+ * it occupied before, without anything overhanging.
+ */
+const PandaFloat = styled("div", {
+  base: {
+    position: "absolute",
+    top: "0",
+    right: "0",
+  },
+});
+
+/**
+ * The hit area — and only the hit area.
+ *
+ * `boxSize="4"` and `layerStyle="fill.solid"` were Chakra props with no Panda
+ * equivalent; their effect is reproduced as real styles. What was NOT
+ * reproduced was a tap target: `boxSize="4"` is **16x16 CSS px**, a third of
+ * this package's stated 48x48 floor, and it came across the extraction
+ * unchanged (NEH-1116) because changing it changes HopperGuard's rendering.
+ * This is that change.
+ *
+ * The split is `StyledTag`'s, which solves the same tension: the BUTTON is the
+ * target and carries no appearance at all, and the chip inside it is what a
+ * reader sees. Sizing the visible circle to 48px instead would put a control
+ * half the width of the 96px preview on top of it.
+ *
+ * `StyledTag` needs negative block margin to stop the target growing its own
+ * tag; here the control is absolutely positioned, so it is already out of
+ * flow and cannot drag the preview's layout with it whatever size it is. The
+ * component test asserts the preview stays 96x96 rather than trusting that.
+ */
+const PandaDeleteTrigger = styled("button", {
+  base: {
+    display: "inline-flex",
+    // Top-end, not centred: the chip keeps the corner position it has always
+    // had, and the extra target grows inwards over the preview — which is
+    // decorative, and the only direction with room.
+    alignItems: "flex-start",
+    justifyContent: "flex-end",
+    // The house floor, stated rather than left to emerge from whatever glyph
+    // a consumer passes — see CLAUDE.md. 48 rather than WCAG 2.5.5 AAA's 44,
+    // because the standard is calibrated for the general population and this
+    // library's largest consumer serves an often-elderly, sometimes
+    // motor-impaired audience.
+    minWidth: "48px",
+    minHeight: "48px",
+    padding: "0",
+    background: "transparent",
+    border: "none",
+    cursor: "pointer",
+  },
+});
+
+/**
+ * What a reader actually sees: the small round chip that used to BE the
+ * button. Same size, same tokens, same appearance — it is now a passenger
+ * inside a target big enough to hit.
+ *
+ * The colours are tokens, never literals, so the control follows the host's
+ * theme and colour mode.
+ */
+const PandaDeleteChip = styled("span", {
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    width: "4",
+    height: "4",
+    borderRadius: "full",
+    lineHeight: "1",
+    bg: "boxBgPrimary",
+    color: "textPrimary",
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: "borderBgPrimary",
+  },
+});
+
+const PandaDropzone = styled("div", {
+  base: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    borderWidth: "1px",
+    borderStyle: "dashed",
+    borderColor: "borderBgPrimary",
+    borderRadius: "md",
+    padding: "4",
+  },
+});
+
+const PandaDropzoneContent = styled("div", {
+  base: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: "2",
+    textAlign: "center",
+  },
+});
+
+/**
+ * The preview image.
+ *
+ * A plain `<img>` on purpose: the source is an object URL for a file the user
+ * just picked, so there is nothing for a framework image component to optimise
+ * — it has no intrinsic dimensions to read, no remote host to whitelist, and no
+ * cacheable URL. (In the originating Next.js app this needed a lint
+ * suppression; this package has no such rule, so it needs none.)
+ */
+function PreviewImage({ file }: { file: File }) {
+  const [src, setSrc] = React.useState<string>();
+  /**
+   * Creating the object URL in an effect keyed on the File — rather than inline
+   * during render — is what stops a blob leaking on every re-render, and the
+   * cleanup is what stops one leaking when the preview is removed.
+   */
+  React.useEffect(() => {
+    const url = URL.createObjectURL(file);
+    setSrc(url);
+    return () => URL.revokeObjectURL(url);
+  }, [file]);
+  if (!src) return null;
+  return (
+    <img
+      src={src}
+      alt={file.name}
+      // Inline rather than a Panda rule: a size a consumer's Panda `include`
+      // glob might never extract is a size that silently does not apply.
+      style={{
+        borderRadius: "8px",
+        objectFit: "cover",
+        width: "96px",
+        height: "96px",
+        display: "block",
+        margin: "0 auto",
+      }}
+    />
+  );
+}
+
+export interface StyledImageUploadProps
+  extends Omit<HTMLStyledProps<"div">, "onChange"> {
+  /** Controlled-ish initial selection. Currently informational only. */
+  value?: File[];
+  onChange?: (files: File[]) => void;
+  /** `1` keeps the input single-select; above 1 sets `multiple`. */
+  maxFiles?: number;
+  accept?: string;
+  buttonText?: string;
+  dropzoneText?: string;
+  /** Decorative glyph inside the upload button. `aria-hidden`. */
+  fileIcon?: React.ReactNode;
+  /** Decorative glyph inside each remove button. `aria-hidden`. */
+  removeIcon?: React.ReactNode;
+}
+
+const FileUploadPreviewOnly = ({
+  removeIcon,
+}: {
+  removeIcon?: React.ReactNode;
+}) => {
+  const { acceptedFiles, removeFile } = useFileUploadContext();
+  if (acceptedFiles.length === 0) return null;
+  return (
+    <PandaItemGroup>
+      {acceptedFiles.map((file) => (
+        <PandaItem p="2" key={file.name}>
+          <PreviewImage file={file} />
+          <PandaFloat>
+            {/*
+              The accessible name is on the BUTTON and names the file, so the
+              glyph is decorative and hidden. A screen-reader user with three
+              previews needs to know which one this removes.
+            */}
+            <PandaDeleteTrigger
+              type="button"
+              aria-label={`Remove ${file.name}`}
+              onClick={() => removeFile(file)}
+            >
+              <PandaDeleteChip aria-hidden="true">{removeIcon}</PandaDeleteChip>
+            </PandaDeleteTrigger>
+          </PandaFloat>
+        </PandaItem>
+      ))}
+    </PandaItemGroup>
+  );
+};
+
+const FileUploadDropzoneOnly = ({
+  buttonText,
+  dropzoneText,
+  fileIcon,
+}: {
+  buttonText: string;
+  dropzoneText: string;
+  fileIcon?: React.ReactNode;
+}) => {
+  const { openPicker } = useFileUploadContext();
+  return (
+    <PandaDropzone
+      width="100%"
+      cursor="pointer"
+      onClick={openPicker}
+      onDragOver={(e) => e.preventDefault()}
+      onDrop={(e) => e.preventDefault()}
+    >
+      <PandaDropzoneContent cursor="pointer">
+        <StyledText cursor="pointer">{dropzoneText}</StyledText>
+        {/*
+          A real <button>, not the dropzone div with a handler: the control must
+          be reachable and operable by KEYBOARD, and a div is neither focusable
+          nor Enter/Space-activated. `stopPropagation` keeps the click from also
+          reaching the dropzone and opening the picker twice.
+        */}
+        <StyledButton
+          type="button"
+          onClick={(e: React.MouseEvent) => {
+            e.stopPropagation();
+            openPicker();
+          }}
+        >
+          {buttonText}
+          {fileIcon ? <span aria-hidden="true">{fileIcon}</span> : null}
+        </StyledButton>
+      </PandaDropzoneContent>
+    </PandaDropzone>
+  );
+};
+
+export function StyledImageUpload({
+  onChange,
+  maxFiles = 1,
+  accept = "image/*",
+  buttonText = "Upload Image",
+  dropzoneText = "Drag and drop an image or",
+  fileIcon,
+  removeIcon,
+  ...vStackProps
+}: StyledImageUploadProps) {
+  log.trace("StyledImageUpload rendered");
+  const [acceptedFiles, setAcceptedFiles] = React.useState<File[]>([]);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+
+  const commit = React.useCallback(
+    (files: File[]) => {
+      const limited = maxFiles > 0 ? files.slice(0, maxFiles) : files;
+      setAcceptedFiles(limited);
+      onChange?.(limited);
+    },
+    [maxFiles, onChange],
+  );
+
+  const ctx = React.useMemo<FileUploadContextValue>(
+    () => ({
+      acceptedFiles,
+      openPicker: () => inputRef.current?.click(),
+      removeFile: (file) =>
+        commit(acceptedFiles.filter((f) => f.name !== file.name)),
+    }),
+    [acceptedFiles, commit],
+  );
+
+  return (
+    <FileUploadContext.Provider value={ctx}>
+      {/*
+        Chakra's HiddenInput. `display: none` would DETACH it from the
+        accessibility tree; it is visually hidden the standard way instead so it
+        stays reachable and stays a real form control.
+      */}
+      <input
+        ref={inputRef}
+        type="file"
+        accept={accept}
+        multiple={maxFiles > 1}
+        onChange={(e) => commit(Array.from(e.target.files ?? []))}
+        style={{
+          position: "absolute",
+          width: "1px",
+          height: "1px",
+          padding: 0,
+          margin: "-1px",
+          overflow: "hidden",
+          clip: "rect(0 0 0 0)",
+          whiteSpace: "nowrap",
+          border: 0,
+        }}
+      />
+      <PandaVStack gap={2} {...vStackProps}>
+        {acceptedFiles.length === 0 ? (
+          <FileUploadDropzoneOnly
+            buttonText={buttonText}
+            dropzoneText={dropzoneText}
+            fileIcon={fileIcon}
+          />
+        ) : (
+          <FileUploadPreviewOnly removeIcon={removeIcon} />
+        )}
+      </PandaVStack>
+    </FileUploadContext.Provider>
+  );
+}
+
+export default StyledImageUpload;

package/src/components/StyledTable.tsx

@@ -0,0 +1,222 @@
+"use client";
+
+import React from "react";
+import { styled } from "styled-system/jsx";
+import { log } from "../config/logger";
+import StyledBox from "./StyledBox";
+import StyledScrollbar from "./StyledScrollbar";
+
+/**
+ * A data table that renders real table elements.
+ *
+ * Extracted from HopperGuard, where it began as Chakra's `Table.*` compound
+ * component. Chakra rendered real `<table>` markup and the app's e2e spec
+ * asserts `toHaveRole("table")`, so every part here is pinned to the semantic
+ * element Chakra produced rather than to a styled `<div>`. A div grid is
+ * pixel-identical and an accessibility regression: screen readers announce row
+ * and column position from the table role, and lose it entirely on divs.
+ *
+ * The compound shape is deliberate. `Header` takes a column list because that
+ * is the shape every consumer already had; the rest are thin passthroughs so a
+ * caller can drop to raw rows and cells whenever the list shape does not fit.
+ */
+
+/** A column for `StyledTable.Header`. Extra props reach the `<th>`. */
+export interface ColumnDefinition
+  extends React.ComponentProps<typeof PandaTableColumnHeader> {
+  key: string;
+  label: string;
+}
+
+const PandaTableRoot = styled("table", {
+  base: {
+    borderCollapse: "collapse",
+    textAlign: "start",
+    verticalAlign: "top",
+    // Digits share a column width, so numeric cells line up down the table.
+    fontVariantNumeric: "lining-nums tabular-nums",
+    // MEASURED off the originating Chakra build with getComputedStyle, not
+    // derived from tokens: font 14px / line-height 20px, cells 12px on every
+    // side, a 1px rule under each cell. Reasoning from the token scale instead
+    // (fontSize md, py 2) put the table 51px too tall — the font, not the
+    // padding, drove the difference.
+    fontSize: "14px",
+    lineHeight: "20px",
+  },
+  variants: {
+    /**
+     * `size` was a Chakra recipe prop. Without a variant declared here it would
+     * fall through to the DOM as an invalid `size` attribute on `<table>`.
+     *
+     * Only `md` is measured against the original — it is what the visual
+     * baseline captured. `sm` and `lg` are proportional and UNVERIFIED; treat
+     * them as a reasonable scale rather than as a reproduction of anything.
+     */
+    size: {
+      sm: { "& th, & td": { padding: "8px" } },
+      md: { "& th, & td": { padding: "12px" } },
+      lg: { "& th, & td": { padding: "16px" } },
+    },
+  },
+  defaultVariants: { size: "md" },
+});
+
+const PandaTableHeader = styled("thead");
+const PandaTableBody = styled("tbody");
+const PandaTableFooter = styled("tfoot");
+const PandaTableRow = styled("tr");
+
+/**
+ * The 1px rule under each cell.
+ *
+ * Chakra's own CSS drew this. `border="sm"` on the cell emits NOTHING — an
+ * empty computed `border` shorthand on a real `<td>` — so it is restored
+ * explicitly.
+ *
+ * `borderBgPrimary` is the token, never a palette literal: a hardcoded
+ * `neutral.200` is invisible to the host's theme and does not follow the colour
+ * mode, which is the whole reason this package refuses literal colours.
+ *
+ * ## Longhands, and why the obvious shorthand is wrong
+ *
+ * The originating app wrote `borderBottom: "1px solid"` alongside
+ * `borderColor: <token>`. That looks equivalent and is not: `border-bottom` is
+ * a SHORTHAND, so it also sets `border-bottom-color`, and omitting the colour
+ * resets it to its initial value — `currentColor`. Whichever declaration Panda
+ * emits second wins, so the cell rule painted the text colour (black on a light
+ * theme) instead of the token, on every table.
+ *
+ * That is a false-pass waiting to happen, because black IS a real colour: a
+ * test asserting only "the border resolved to something" goes green on it.
+ * `StyledTable.ct.tsx` re-points the custom property and asserts the border
+ * follows, which is the assertion that actually distinguishes the two.
+ */
+const CELL_RULE = {
+  borderBottomWidth: "1px",
+  borderBottomStyle: "solid",
+  borderBottomColor: "borderBgPrimary",
+} as const;
+
+const PandaTableColumnHeader = styled("th", {
+  base: { fontWeight: "medium", textAlign: "start", ...CELL_RULE },
+});
+const PandaTableCell = styled("td", { base: { ...CELL_RULE } });
+const PandaTableCaption = styled("caption");
+
+export type StyledTableProps = React.ComponentProps<typeof PandaTableRoot>;
+
+const StyledTable: React.FC<StyledTableProps> = ({ children, ...props }) => {
+  log.trace("StyledTable rendered");
+  return (
+    // `overflow: hidden` on the outer box clips the scroll container's corners
+    // to the box radius; the scrollbar inside is what actually scrolls.
+    <StyledBox
+      overflow="hidden"
+      data-testid="styled-table-container"
+      border={0}
+      py={0}
+      px={0}
+    >
+      <StyledScrollbar p={0} data-testid="styled-table-scrollbar" border={0}>
+        <PandaTableRoot {...props} data-testid="styled-table-root">
+          {children}
+        </PandaTableRoot>
+      </StyledScrollbar>
+    </StyledBox>
+  );
+};
+
+export interface StyledTableHeaderProps {
+  columns: ColumnDefinition[];
+}
+
+const StyledHeader: React.FC<StyledTableHeaderProps> = ({ columns }) => (
+  <PandaTableHeader>
+    <PandaTableRow>
+      {columns.map(({ key, label, ...rest }) => (
+        <PandaTableColumnHeader key={key} {...rest}>
+          {label}
+        </PandaTableColumnHeader>
+      ))}
+    </PandaTableRow>
+  </PandaTableHeader>
+);
+StyledHeader.displayName = "StyledTable.Header";
+
+export interface StyledTableBodyProps {
+  children: React.ReactNode;
+  header?: React.ReactNode;
+  footer?: React.ReactNode;
+}
+
+/**
+ * `header` and `footer` render as siblings, not children — `<thead>` and
+ * `<tfoot>` are invalid inside `<tbody>`, and nesting them there is silently
+ * reparented by the browser rather than reported.
+ */
+const StyledBody: React.FC<StyledTableBodyProps> = ({
+  children,
+  header,
+  footer,
+}) => (
+  <>
+    {header}
+    <PandaTableBody>{children}</PandaTableBody>
+    {footer}
+  </>
+);
+StyledBody.displayName = "StyledTable.Body";
+
+type StyledTableFooterProps = React.ComponentProps<typeof PandaTableFooter>;
+const StyledFooter: React.FC<StyledTableFooterProps> = (props) => (
+  <PandaTableFooter {...props} />
+);
+StyledFooter.displayName = "StyledTable.Footer";
+
+type StyledTableRowProps = React.ComponentProps<typeof PandaTableRow>;
+const StyledRow: React.FC<StyledTableRowProps> = (props) => (
+  <PandaTableRow {...props} />
+);
+StyledRow.displayName = "StyledTable.Row";
+
+type StyledColumnHeaderProps = React.ComponentProps<
+  typeof PandaTableColumnHeader
+>;
+const StyledColumnHeader: React.FC<StyledColumnHeaderProps> = (props) => (
+  <PandaTableColumnHeader {...props} />
+);
+StyledColumnHeader.displayName = "StyledTable.ColumnHeader";
+
+type StyledTableCellProps = React.ComponentProps<typeof PandaTableCell>;
+const StyledCell: React.FC<StyledTableCellProps> = (props) => (
+  <PandaTableCell {...props} />
+);
+StyledCell.displayName = "StyledTable.Cell";
+
+type StyledTableCaptionProps = React.ComponentProps<typeof PandaTableCaption>;
+const StyledCaption: React.FC<StyledTableCaptionProps> = (props) => (
+  <PandaTableCaption {...props} />
+);
+StyledCaption.displayName = "StyledTable.Caption";
+
+interface StyledTableComponent extends React.FC<StyledTableProps> {
+  Header: typeof StyledHeader;
+  Body: typeof StyledBody;
+  Footer: typeof StyledFooter;
+  Row: typeof StyledRow;
+  ColumnHeader: typeof StyledColumnHeader;
+  Cell: typeof StyledCell;
+  Caption: typeof StyledCaption;
+}
+
+const StyledTableExport = StyledTable as StyledTableComponent;
+StyledTableExport.Header = StyledHeader;
+StyledTableExport.Body = StyledBody;
+StyledTableExport.Footer = StyledFooter;
+StyledTableExport.Row = StyledRow;
+StyledTableExport.ColumnHeader = StyledColumnHeader;
+StyledTableExport.Cell = StyledCell;
+StyledTableExport.Caption = StyledCaption;
+
+export { StyledTableExport as StyledTable };
+export default StyledTableExport;

package/src/components/StyledTooltip.tsx

@@ -226,6 +226,59 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
    */
   const [focusableAncestor, setFocusableAncestor] = useState<HTMLElement | null>(null);
 
+  /**
+   * Whether the layout effect below has yet decided WHERE the click-mode help
+   * control belongs (NEH-965).
+   *
+   * The control is a real `<button>`, and until the trigger has been measured
+   * the component cannot know whether it is standing inside one. Rendering it
+   * optimistically and moving it afterwards is not an option: React validates
+   * DOM nesting at *render* time, against the React tree, so a single pass
+   * with `<button>` inside `<button>` warns and — on a server-rendered host
+   * like hopper-web — produces a hydration error, whatever the DOM ends up
+   * looking like a moment later.
+   *
+   * So the first pass renders no control at all and the second one puts it
+   * where it belongs. Both effects here are layout effects, so that settles
+   * before paint and before hydration compares anything: there is no frame in
+   * which a reader could see the control missing, and no server/client
+   * mismatch, because the server also renders nothing.
+   */
+  const [helpPlacementSettled, setHelpPlacementSettled] = useState(false);
+
+  /**
+   * The element the click-mode help control is rendered into when the trigger
+   * sits inside something focusable (NEH-965).
+   *
+   * `HelpTrigger` renders beside the child, inside the trigger wrapper. When
+   * the tooltipped thing is an icon inside an icon button that lands the
+   * control *inside* that button:
+   *
+   *     <button aria-label="Expand">   <- the consumer's control
+   *       <div>                        <- TooltipTrigger
+   *         <svg aria-hidden />
+   *         <button aria-label="More information">?</button>   <- invalid
+   *
+   * `<button>` cannot be a descendant of `<button>`, and this is not a
+   * preference anybody opted into: `isClick` is `trigger === "click" ||
+   * !canHover`, so it is the DEFAULT rendering on every phone and tablet.
+   *
+   * Simply not rendering the control would trade invalid HTML for an
+   * unreachable explanation — on a device that cannot hover there is no hover,
+   * and tapping the button activates it rather than explaining it. So the
+   * control moves *out* instead: a span inserted immediately after the
+   * focusable ancestor, portalled into. Valid HTML, still visible, still
+   * tappable, still in the tab sequence, and it scrolls with the page because
+   * it sits in normal flow rather than being positioned over anything.
+   *
+   * `inline-flex` on the host rather than `display: contents`: contents would
+   * let the control participate in the ancestor's parent layout directly, but
+   * it was removed from the accessibility tree by browsers this package's
+   * audience is still using, and an invisible help control is the bug we are
+   * fixing.
+   */
+  const [helpHost, setHelpHost] = useState<HTMLElement | null>(null);
+
   /**
    * True when something else — a descendant or an ancestor — already puts this
    * trigger's content in the tab sequence. When it does, the trigger must add
@@ -287,6 +340,10 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
       ? null
       : node?.parentElement?.closest<HTMLElement>(FOCUSABLE_SELECTOR) ?? null;
     setFocusableAncestor((prev) => (prev === ancestor ? prev : ancestor));
+    // Measured — the next render may place the help control (NEH-965). Set
+    // before the `!node` bail so a trigger that never mounted a node does not
+    // leave click mode permanently without its control.
+    setHelpPlacementSettled(true);
 
     if (!node) return;
 
@@ -299,9 +356,21 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
       .join(" ")
       .replace(/\s+/g, " ")
       .trim();
+    // With a focusable ancestor the help control is rendered OUTSIDE it
+    // (NEH-965), so the ancestor no longer supplies context by containment and
+    // the control has to carry the subject in its own name. "More information"
+    // sitting on its own next to a button called "Expand" names nothing —
+    // which is the twenty-identical-controls problem NEH-769 fixed for the
+    // inline case, reappearing one level up.
+    const ancestorText = ancestor
+      ? (ancestor.getAttribute("aria-label") ?? ancestor.textContent ?? "")
+          .replace(/\s+/g, " ")
+          .trim()
+      : "";
+    const subject = ownText || ancestorText;
     // Long enough to distinguish twenty controls, short enough that a screen
     // reader does not read a paragraph before the reader can act on it.
-    setSubjectLabel(ownText.length > 80 ? `${ownText.slice(0, 80).trimEnd()}…` : ownText);
+    setSubjectLabel(subject.length > 80 ? `${subject.slice(0, 80).trimEnd()}…` : subject);
 
     // parentElement, not the node itself: closest() would match our own
     // aria-label once we set one, and the answer would flip every render.
@@ -361,6 +430,67 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     };
   }, [focusableAncestor, isClick, show, hide]);
 
+  /**
+   * Insert the host for the portalled help control, immediately after the
+   * focusable ancestor (NEH-965). A layout effect, so the control is in place
+   * before paint.
+   */
+  useLayoutEffect(() => {
+    if (!isClick || !focusableAncestor || typeof document === "undefined") {
+      setHelpHost(null);
+      return;
+    }
+    const host = document.createElement("span");
+    // Named so a consumer reading the DOM can see whose node this is, and so a
+    // test can assert the control landed outside the ancestor rather than
+    // merely that it exists somewhere.
+    host.setAttribute("data-stonedog-tooltip-help-host", "");
+    host.style.display = "inline-flex";
+    host.style.verticalAlign = "middle";
+    focusableAncestor.after(host);
+    setHelpHost(host);
+    return () => {
+      host.remove();
+      setHelpHost(null);
+    };
+  }, [isClick, focusableAncestor]);
+
+  /**
+   * Keep the host beside its ancestor when React MOVES the ancestor.
+   *
+   * The host is a node this component inserts, not one React renders, so React
+   * does not move it with the ancestor: reordering a row of icon buttons
+   * leaves every help control behind at its old index. Measured before fixing,
+   * two buttons swapped:
+   *
+   *     before  BTN(Expand) HOST(Help: Expand) BTN(Collapse) HOST(Help: Collapse)
+   *     after   HOST(Help: Expand) BTN(Collapse) HOST(Help: Collapse) BTN(Expand)
+   *
+   * — every control now beside the wrong button, which for an accessibility
+   * affordance is worse than the nesting it replaced.
+   *
+   * Re-running the effect above cannot catch this. Its dependency is the
+   * ancestor NODE, and a moved node is the same node, so nothing changes and
+   * nothing re-runs. Hence a deliberately dependency-free layout effect: it
+   * re-asserts the placement on every commit, before paint, and costs two DOM
+   * property reads on a path that only exists in click mode inside a focusable
+   * ancestor.
+   *
+   * Scope worth stating rather than implying: this follows a move that
+   * RE-RENDERS this component, which is what a list reorder does. A subtree
+   * memoised so hard that React moves it without rendering it would not be
+   * followed. A `MutationObserver` on the parent would cover that too, and is
+   * deliberately not here — its callback is a microtask, so it could not be
+   * asserted in the tier that can see this at all, and an untested guard is
+   * the thing this package's rules are most emphatic about.
+   */
+  useLayoutEffect(() => {
+    if (!helpHost || !focusableAncestor) return;
+    if (!focusableAncestor.isConnected) return;
+    if (helpHost.previousSibling === focusableAncestor) return;
+    focusableAncestor.after(helpHost);
+  });
+
   useLayoutEffect(() => {
     if (visible && triggerRef.current && tooltipRef.current) {
       const triggerRect = triggerRef.current.getBoundingClientRect();
@@ -566,19 +696,40 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   const resolvedHelpLabel =
     helpLabel ?? (subjectLabel ? `Help: ${subjectLabel}` : "More information");
 
-  const helpControl = isClick ? (
-    <HelpTrigger
-      ref={helpRef}
-      type="button"
-      side={helpGoesFirst ? "before" : "after"}
-      aria-label={resolvedHelpLabel}
-      aria-expanded={visible}
-      aria-controls={visible ? tooltipId : undefined}
-      onClick={() => setVisible((open) => !open)}
-    >
-      ?
-    </HelpTrigger>
-  ) : null;
+  /**
+   * The click-mode control — rendered only once its home is known, see
+   * `helpPlacementSettled`.
+   *
+   * `stopPropagation` is load-bearing rather than defensive. A React portal
+   * bubbles its events through the REACT tree, not the DOM tree, so once this
+   * control is portalled out of the icon button it is still, as far as React
+   * is concerned, inside it — and a press on "?" would fire the button's own
+   * `onClick`. That is precisely the collision this fix exists to remove, so
+   * it is stopped for the inline case too: pressing "?" asks for an
+   * explanation, and must never also do the thing being explained.
+   */
+  const helpControl =
+    isClick && helpPlacementSettled ? (
+      <HelpTrigger
+        ref={helpRef}
+        type="button"
+        side={helpGoesFirst ? "before" : "after"}
+        aria-label={resolvedHelpLabel}
+        aria-expanded={visible}
+        aria-controls={visible ? tooltipId : undefined}
+        onMouseDown={(event: React.MouseEvent) => event.stopPropagation()}
+        onClick={(event: React.MouseEvent) => {
+          event.stopPropagation();
+          setVisible((open) => !open);
+        }}
+      >
+        ?
+      </HelpTrigger>
+    ) : null;
+
+  // Inside a focusable ancestor the control is portalled out to `helpHost`;
+  // everywhere else it stays where it has always been, beside the child.
+  const inlineHelpControl = focusableAncestor ? null : helpControl;
 
   return (
     <>
@@ -628,10 +779,11 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
         aria-describedby={!insideFocusable && visible ? tooltipId : undefined}
         {...rest}
       >
-        {helpGoesFirst && helpControl}
+        {helpGoesFirst && inlineHelpControl}
         {children}
-        {!helpGoesFirst && helpControl}
+        {!helpGoesFirst && inlineHelpControl}
       </TooltipTrigger>
+      {helpControl && helpHost && createPortal(helpControl, helpHost)}
       {visible && typeof document !== "undefined" &&
         createPortal(
           <TooltipContent

package/src/index.ts

@@ -210,6 +210,16 @@ export {
 } from "./components/StyledFieldHelp";
 export type { StyledFieldHelpProps } from "./components/StyledFieldHelp";
 
+/**
+ * A file dropzone with image previews. Ships no artwork: both glyph slots
+ * default to nothing and the host passes its own icon set if it wants one.
+ */
+export {
+  default as StyledImageUpload,
+  StyledImageUpload as ImageUpload,
+} from "./components/StyledImageUpload";
+export type { StyledImageUploadProps } from "./components/StyledImageUpload";
+
 // ---------------------------------------------------------------------------
 // Components that were blocked on a runtime dependency until NEH-430 gave each
 // a seam with a working default. None of them adds a dependency; the host
@@ -316,6 +326,18 @@ export { DL_VARIANTS } from "./components/StyledDefinitionList";
 export { default as StyledSparkLine } from "./components/StyledSparkLine";
 export type { StyledSparkLineProps } from "./components/StyledSparkLine";
 
+/**
+ * A data table that renders real `<table>` markup rather than a div grid — the
+ * table role is what carries row and column position to a screen reader.
+ */
+export { default as StyledTable, StyledTable as Table } from "./components/StyledTable";
+export type {
+  StyledTableProps,
+  StyledTableHeaderProps,
+  StyledTableBodyProps,
+  ColumnDefinition,
+} from "./components/StyledTable";
+
 // ---------------------------------------------------------------------------
 // Notifications
 // ---------------------------------------------------------------------------