@stonedogcode/style 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "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,335 @@
+"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. */
+const PandaFloat = styled("div", {
+  base: {
+    position: "absolute",
+    top: "0",
+    right: "0",
+    transform: "translate(40%, -40%)",
+  },
+});
+
+/**
+ * `boxSize="4"` and `layerStyle="fill.solid"` were Chakra props with no Panda
+ * equivalent — they do not exist on a `styled("button")` and the type-check
+ * rejects both. Their effect is reproduced as real styles.
+ *
+ * The colours are tokens, never literals, so the control follows the host's
+ * theme and colour mode.
+ */
+const PandaDeleteTrigger = styled("button", {
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    width: "4",
+    height: "4",
+    borderRadius: "full",
+    cursor: "pointer",
+    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)}
+            >
+              {removeIcon ? (
+                <span aria-hidden="true">{removeIcon}</span>
+              ) : null}
+            </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/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
 // ---------------------------------------------------------------------------