@stonedogcode/style 0.9.0

package/src/components/StyledSparkLine.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+import React from "react";
+
+/**
+ * A tiny inline trend line — the shape of a series, at the size of a word.
+ *
+ * It is deliberately not a chart. No axes, no ticks, no tooltip: a sparkline
+ * earns its place by sitting *inside* a sentence or a table cell, and anything
+ * that makes it want its own space has turned it into a chart that belongs in
+ * a chart component.
+ *
+ * ## Two defects fixed on the way across
+ *
+ * **It hardcoded the host's custom-property namespace.** The default colour was
+ * `var(--hopper-text-primary-text, #666)` — a literal `--hopper-*` property, so
+ * the component only themed correctly inside an app that had chosen that
+ * prefix. `cssVarPrefix` is configurable and still defaults to `"hopper"`
+ * (NEH-256), so a consumer that renames it would silently have got `#666`
+ * everywhere. Same defect class as NEH-171.
+ *
+ * The replacement is `currentColor`, which is better than reaching for any
+ * token: a sparkline is punctuation inside running text, so inheriting the
+ * colour of the text it sits in is what a reader expects, and it costs the
+ * host nothing to define. A caller wanting a specific colour still passes one.
+ *
+ * **It was invisible to assistive technology.** A bare `<svg>` with no role and
+ * no name is skipped entirely by a screen reader, so the trend simply did not
+ * exist for anyone not looking at it. It now renders as `role="img"` with a
+ * name, and `label` is required for that reason — there is no sensible default,
+ * because only the caller knows what the series *is*.
+ *
+ * If the surrounding text already states the trend, pass `label=""`: that marks
+ * it explicitly decorative (`aria-hidden`) rather than leaving it unnamed by
+ * accident. The distinction is the point — an empty string is a decision, a
+ * missing prop is an oversight.
+ */
+
+export interface StyledSparkLineProps {
+  /** The series, in order. Fewer than two points renders nothing. */
+  data: number[];
+  /**
+   * What the line describes, for assistive tech — e.g. "Blood pressure, last
+   * 7 days". Pass `""` to mark it decorative when the surrounding copy
+   * already says it.
+   */
+  label: string;
+  width?: number;
+  height?: number;
+  /** Defaults to `currentColor` — it inherits from the text around it. */
+  color?: string;
+  fillOpacity?: number;
+}
+
+const StyledSparkLine: React.FC<StyledSparkLineProps> = ({
+  data,
+  label,
+  width = 80,
+  height = 24,
+  color = "currentColor",
+  fillOpacity = 0.1,
+}) => {
+  if (!data || data.length < 2) return null;
+
+  const max = Math.max(...data);
+  const min = Math.min(...data);
+  const range = max - min || 1;
+  const padding = 1;
+
+  const points = data.map((v, i) => {
+    const x = padding + (i / (data.length - 1)) * (width - padding * 2);
+    const y = padding + (1 - (v - min) / range) * (height - padding * 2);
+    return `${x},${y}`;
+  });
+
+  const linePoints = points.join(" ");
+
+  // Closed path for the fill area: the line, then down and back along the
+  // baseline.
+  const firstX = padding;
+  const lastX = padding + (width - padding * 2);
+  const fillPath = `M${points[0]} ${points
+    .slice(1)
+    .map((p) => `L${p}`)
+    .join(" ")} L${lastX},${height - padding} L${firstX},${height - padding} Z`;
+
+  const decorative = label === "";
+
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      // Inline, not a Panda prop: these are layout facts the component owns,
+      // and `flexShrink` in particular is what stops a table cell squashing it
+      // into a vertical line.
+      style={{ display: "block", flexShrink: 0 }}
+      // An `<svg>` defaults to `role="graphics-document"` in some engines and
+      // to nothing in others. Naming the role removes the difference.
+      role={decorative ? undefined : "img"}
+      aria-hidden={decorative ? true : undefined}
+      aria-label={decorative ? undefined : label}
+    >
+      <path d={fillPath} fill={color} opacity={fillOpacity} />
+      <polyline
+        points={linePoints}
+        fill="none"
+        stroke={color}
+        strokeWidth="1.5"
+        strokeLinejoin="round"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+};
+
+StyledSparkLine.displayName = "StyledSparkLine";
+
+export default StyledSparkLine;

package/src/components/StyledSpinner.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+import React from "react";
+import StyledHStack from "./StyledHStack";
+import StyledText from "./StyledText";
+import { log } from "../config/logger";
+
+/**
+ * A "still working" indicator: a label followed by animating dots.
+ *
+ * Text rather than a rotating graphic, deliberately. This came out of a product
+ * for an often-elderly audience, where a spinner that says *"Loading…"* is
+ * understood immediately and an abstract rotating shape is not. It also degrades
+ * honestly under `prefers-reduced-motion`: the dots change once every 500ms
+ * rather than spinning continuously.
+ *
+ * ## What was deliberately left behind
+ *
+ * The originating component had a second mode, `spinLogo`, that rotated
+ * HopperGuard's brand mark. That is **branding, not a primitive** — the same
+ * reason this package ships no icons — so it stays in the app, which keeps its
+ * own `StyledSpinner` wrapping this one for the dots path.
+ *
+ * Five props went with it: `thickness`, `speed`, `color`, `emptyColor` and
+ * `logoSize` were all declared, accepted, and **silently discarded** — none was
+ * read, and a search of the originating app found zero call sites passing any of
+ * them. A prop that does nothing is worse than a missing one: it reads as a
+ * supported knob and fails silently when someone turns it.
+ *
+ * `size` is gone for the same reason. It sized the logo wrapper only, so on the
+ * dots path it never did anything.
+ */
+
+/** How long each dot stays before the next is added. */
+const DOT_INTERVAL_MS = 500;
+const DOT_STATES = [".", "..", "..."] as const;
+
+export interface StyledSpinnerProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * What the user is waiting for. A string is wrapped in `StyledText` so it
+   * picks up the app-wide font-size profile; a node is rendered as given.
+   *
+   * Say what is loading where you can — "Loading" alone tells someone nothing
+   * about whether to wait or navigate away.
+   */
+  loadText?: React.ReactNode;
+}
+
+export const StyledSpinner = ({
+  loadText = "Loading",
+  ...rest
+}: StyledSpinnerProps) => {
+  log.trace("StyledSpinner rendered");
+
+  const [dotIndex, setDotIndex] = React.useState(0);
+
+  React.useEffect(() => {
+    const interval = setInterval(
+      () => setDotIndex((i) => (i + 1) % DOT_STATES.length),
+      DOT_INTERVAL_MS,
+    );
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    // `role="status"` — an implicit `aria-live="polite"` region, so a screen
+    // reader announces "Loading" once when this appears instead of leaving the
+    // user with silence. The original had no role at all: sighted users got an
+    // indicator and everyone else got nothing, which is a WCAG 4.1.3 gap rather
+    // than a missing nicety.
+    <StyledHStack gap={1} role="status" {...rest}>
+      {typeof loadText === "string" ? (
+        <StyledText>{loadText}</StyledText>
+      ) : (
+        loadText
+      )}
+      {/*
+        The dots are decorative and deliberately hidden. The label beside them
+        already says what is happening, and inside a live region a screen reader
+        would otherwise re-announce the whole thing twice a second as they
+        change — turning a helpful status into unusable chatter.
+      */}
+      <StyledText aria-hidden="true">{DOT_STATES[dotIndex]}</StyledText>
+    </StyledHStack>
+  );
+};
+
+StyledSpinner.displayName = "StyledSpinner";
+
+export default StyledSpinner;

package/src/components/StyledStack.tsx

@@ -0,0 +1,62 @@
+import React from "react";
+import StyledHStack, { StyledHStackProps } from "./StyledHStack";
+import StyledVStack, { StyledVStackProps } from "./StyledVStack";
+import { ConditionalValue } from "styled-system/types";
+import { Property } from "csstype";
+
+export interface StyledStackProps
+  extends Omit<StyledHStackProps, "direction">,
+    Omit<StyledVStackProps, "direction"> {
+  direction?: ConditionalValue<Property.FlexDirection>;
+  divider?: React.ReactNode;
+}
+
+export const StyledStack: React.FC<StyledStackProps> = ({
+  direction = "column",
+  divider,
+  children,
+  ...rest
+}) => {
+  const isResponsive = typeof direction === "object";
+
+  const childrenWithDividers = divider
+    ? React.Children.toArray(children).flatMap((child, index) => {
+        if (index === 0) {
+          return [<React.Fragment key={`child-${index}`}>{child}</React.Fragment>];
+        }
+        return [
+          <React.Fragment key={`divider-${index}`}>{divider}</React.Fragment>,
+          <React.Fragment key={`child-${index}`}>{child}</React.Fragment>,
+        ];
+      })
+    : children;
+
+  if (isResponsive) {
+    const responsiveDirections = direction as Record<string, string>;
+    const baseDirection = responsiveDirections.base || "column";
+
+    if (baseDirection === "column") {
+      return (
+        <StyledVStack {...rest} flexDirection={direction}>
+          {childrenWithDividers}
+        </StyledVStack>
+      );
+    } else {
+      return (
+        <StyledHStack {...rest} flexDirection={direction}>
+          {childrenWithDividers}
+        </StyledHStack>
+      );
+    }
+  }
+
+  if (direction === "row") {
+    return <StyledHStack {...rest}>{childrenWithDividers}</StyledHStack>;
+  }
+
+  return <StyledVStack {...rest}>{childrenWithDividers}</StyledVStack>;
+};
+
+StyledStack.displayName = "StyledStack";
+
+export default StyledStack;

package/src/components/StyledText.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import { log } from "../config/logger";
+import React from "react";
+import { styled } from "styled-system/jsx";
+import { css, cx } from "styled-system/css";
+import StyledTooltip from "./StyledTooltip";
+import { useFontSizeProfile } from "../config/style-config";
+import { fontSizeMap } from "../config/font-size";
+import type { AllowedTextVariant } from "../config/types";
+import { textRecipe } from "styled-system/recipes";
+
+const PandaText = styled("span", textRecipe);
+
+export interface StyledTextProps
+  extends React.ComponentProps<typeof PandaText> {
+  children?: React.ReactNode | undefined;
+
+  tooltip?: React.ReactNode | undefined;
+  as?: React.ElementType | undefined; // Explicitly add the 'as' prop
+  size?: keyof typeof fontSizeMap | undefined;
+  fixedSize?: boolean | undefined;
+  color?: string | undefined;
+  ellipsis?: boolean | undefined;
+  wrap?: boolean | undefined;
+
+  variant?: AllowedTextVariant | undefined;
+}
+
+const StyledText = React.forwardRef<HTMLSpanElement, StyledTextProps>((props, ref) => {
+  log.trace("StyledText rendered");
+  const {
+    children,
+    tooltip,
+    size,
+    fixedSize,
+    color = "textPrimary",
+    variant,
+    style,
+    ellipsis,
+    wrap,
+    textAlign,
+    className,
+    ...rest
+  } = props;
+  const fontSizeProfile = useFontSizeProfile();
+
+  let finalSize;
+  if (size) {
+    finalSize = size;
+  } else if (fixedSize) {
+    finalSize = "md";
+  } else {
+    finalSize = fontSizeProfile;
+  }
+
+  const fontSize = fontSizeMap[finalSize] || fontSizeMap.md;
+
+  const extraStyles: React.CSSProperties = {};
+  if (ellipsis) {
+    extraStyles.textOverflow = "ellipsis";
+    extraStyles.whiteSpace = "nowrap";
+    extraStyles.overflow = "hidden";
+    extraStyles.display = "block";
+  }
+  if (wrap === false) {
+    extraStyles.whiteSpace = "nowrap";
+  }
+
+  const textAlignClass = textAlign ? css({ textAlign }) : "";
+  const combinedClassName = cx(className, textAlignClass);
+
+  const textElement = (
+    <PandaText
+      ref={ref}
+      style={{ fontSize, ...extraStyles, ...style }}
+      color={color}
+      variant={variant}
+      className={combinedClassName}
+      {...rest}
+    >
+      {children}
+    </PandaText>
+  );
+
+  return (
+    <>
+      {tooltip ? (
+        <StyledTooltip tooltip={tooltip}>{textElement}</StyledTooltip>
+      ) : (
+        textElement
+      )}
+    </>
+  );
+});
+
+StyledText.displayName = "StyledText";
+
+export default StyledText;