@atelic-action/ui 0.8.0 → 0.9.0

package/README.md

@@ -41,7 +41,7 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | Import | Exports |
 |---|---|
 | `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
-| `@atelic-action/ui/components` | `NotFound` and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
+| `@atelic-action/ui/components` | `NotFound` and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`, `StarRating`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
 | `@atelic-action/ui/email` | The email components, the theme provider, the plain text helpers, and their prop types (see [Email](#email)) |
 | `@atelic-action/ui/email/render` | `renderEmail` and `renderFailureEmail`, the only entry that imports `react-dom/server` |
 | `@atelic-action/ui/tokens` | `Palette`, `atelicPalette`, `Fonts`, `atelicFonts`, `toThemeCSS`, `themeTokenMap` |
@@ -50,6 +50,7 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | `@atelic-action/ui/styles/base.css` | Resets, the `.mkt` canvas, typography, and layout helpers |
 | `@atelic-action/ui/styles/chrome.css` | Styles for everything under `chrome` |
 | `@atelic-action/ui/styles/components.css` | Layout defaults for everything under `components` |
+| `@atelic-action/ui/styles/star-rating.css` | `StarRating`'s styles alone, for an app that wears none of the site chrome; `components.css` already imports it |
 
 Every component renders from props alone. None reads a config file or a router, so a site maps its own config onto the props in its shell:
 
@@ -261,9 +262,23 @@ The blocks a page composes, each styled in `styles/components.css` inside the `a
 | `StackedBar` | One bar split into the parts of a whole, with a key | A part of zero is keyed and not drawn |
 | `ColumnChart` | A bar a period, the periods in groups that carry a label and a total | Months in quarters is the case it was cut for: a quarter reads against the one before it and the same one a year earlier |
 | `ThresholdScale` | Zones on a scale and a pin for each reading | For a number judged against lines, like a load time against good and poor |
+| `StarRating` | A row of stars showing a rating in half star steps, and taking one when given `onChange` | Each star is two hit targets; picking the current rating clears it. Editable, it is one slider to a keyboard and a screen reader; read only, a picture named by the rating. `fillColor` and `outlineColor` take any CSS color, `size` and `max` set the star and the scale |
+
+**StarRating outside a site.** It is the one component that does not sit under `.mkt` or read a theme token: its styles are in `styles/star-rating.css`, and its two colors are the `--star-fill` and `--star-outline` custom properties, falling back to the text color and a faint tint of it. An app that installs the package for this component alone imports that one sheet, not `components.css`.
 
 **Tones.** `good`, `warn`, `bad`, `info`, and `muted` are the one palette the package carries, because good, a warning, and broken read green, amber, and red whatever the brand is. A component sets `data-tone`, and `--tone`, `--tone-fill`, and `--tone-bg` follow for whatever sits inside. A site's theme may restate `--tone-good` and the rest on `.mkt`; `info` and `muted` come from the theme's own primary and neutral tokens.
 
+## The Gallery
+
+`gallery/` is one static page, The Components, that shows every page component on its own with made up data for a fictional bakery, wearing the practice's own palette and type. It lives at [ui.atelic.me](https://ui.atelic.me), noindexed and disallowed in its `robots.txt`, since it is for the people building with the package and never search inventory. It imports the components and stylesheets from `src/` by relative path rather than from npm, so it always shows the code in the repo, and it reads the package name and version from `package.json` at build time. It sits outside `src/`, so it is never published.
+
+```bash
+bun run gallery:dev    # a dev server on the repo's own source
+bun run gallery:build  # the static page, written to gallery/dist
+```
+
+`vercel.json` builds it the same way and serves `gallery/dist`. Typecheck and lint cover it, and CI builds it, so a component change that breaks the gallery fails CI. **A new page component gets a gallery section in the same change**, with each of its meaningfully different forms shown.
+
 ## Releasing
 
 1. Bump `version` in `package.json` and merge it to `main`: patch for a fix, minor for a new component or prop, major for a breaking prop or class rename.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, and the component library they install",
 	"type": "module",
 	"license": "UNLICENSED",
@@ -28,13 +28,16 @@
 		"./styles/base.css": "./src/styles/base.css",
 		"./styles/chrome.css": "./src/styles/chrome.css",
 		"./styles/components.css": "./src/styles/components.css",
+		"./styles/star-rating.css": "./src/styles/star-rating.css",
 		"./package.json": "./package.json"
 	},
 	"scripts": {
 		"lint": "biome check .",
 		"lint:fix": "biome check . --write",
-		"typecheck": "tsc --noEmit",
-		"test:run": "vitest run"
+		"typecheck": "tsc --noEmit && tsc --noEmit -p gallery",
+		"test:run": "vitest run",
+		"gallery:dev": "vite gallery",
+		"gallery:build": "vite build gallery"
 	},
 	"peerDependencies": {
 		"lucide-react": "^1.23.0",
@@ -47,11 +50,13 @@
 		"@testing-library/react": "^16.0.1",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
+		"@vitejs/plugin-react": "^6.1.1",
 		"jsdom": "^25.0.1",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"typescript": "^5.6.3",
+		"vite": "^8.3.2",
 		"vitest": "^4.0.0"
 	},
 	"trustedDependencies": [

package/src/components/StarRating.tsx

@@ -0,0 +1,153 @@
+import { Star } from "lucide-react";
+import { type CSSProperties, type KeyboardEvent, useState } from "react";
+
+const STEP = 0.5;
+
+export interface StarRatingProps {
+	/** The rating, in half star steps from 0.5 up to `max`; null is unrated. */
+	value: number | null;
+	/** Called with the new rating, or null to clear it. Leave it out for a read only row. */
+	onChange?: (value: number | null) => void;
+	/** How many stars the scale runs to. */
+	max?: number;
+	/** The side of one star, in pixels. */
+	size?: number;
+	/** The color of a filled star: any CSS color. Defaults to the text color around it. */
+	fillColor?: string;
+	/** The color of a star's outline: any CSS color. Defaults to a faint tint of the text color. */
+	outlineColor?: string;
+	/** What a screen reader calls the row. */
+	label?: string;
+	className?: string;
+}
+
+/** "4.5 stars", "1 star", "Not rated": the rating as a person would say it. */
+export function describeStarRating(value: number | null): string {
+	if (value === null) return "Not rated";
+	return `${value} ${value === 1 ? "star" : "stars"}`;
+}
+
+/**
+ * A row of stars that shows a rating in half star steps and, given `onChange`,
+ * takes one. Each star is two hit targets, its left half and its right, so a
+ * pointer lands on 3.5 or 4 without a second control. Picking the rating
+ * already set clears it, which is the only way back to unrated and needs no
+ * button of its own.
+ *
+ * To a keyboard and a screen reader an editable row is one slider: the arrows
+ * move half a star, Home clears, End is the top of the scale. The halves stay
+ * out of the tab order, so the row is one stop rather than ten. Without
+ * `onChange` it is a picture with the rating as its name.
+ *
+ * The two colors are the `--star-fill` and `--star-outline` custom properties.
+ * `fillColor` and `outlineColor` set them on this row; a site may also set
+ * them in its own CSS for every row at once.
+ */
+export function StarRating({
+	value,
+	onChange,
+	max = 5,
+	size = 24,
+	fillColor,
+	outlineColor,
+	label = "Rating",
+	className,
+}: StarRatingProps) {
+	const [hover, setHover] = useState<number | null>(null);
+	const shown = hover ?? value ?? 0;
+
+	const style = {
+		"--star-size": `${size}px`,
+		...(fillColor ? { "--star-fill": fillColor } : {}),
+		...(outlineColor ? { "--star-outline": outlineColor } : {}),
+	} as CSSProperties;
+	const classes = ["star-rating", className].filter(Boolean).join(" ");
+
+	const stars = Array.from({ length: max }, (_, i) => i + 1).map((star) => {
+		const fill = shown >= star ? "100%" : shown >= star - STEP ? "50%" : "0%";
+		return (
+			<span key={star} className="star-rating-star">
+				<Star aria-hidden="true" size={size} className="star-rating-outline" />
+				<span aria-hidden="true" className="star-rating-fill" style={{ width: fill }}>
+					<Star size={size} />
+				</span>
+				{onChange &&
+					[star - STEP, star].map((rating, half) => (
+						<button
+							key={rating}
+							type="button"
+							tabIndex={-1}
+							aria-label={describeStarRating(rating)}
+							className={`star-rating-hit ${half === 0 ? "is-left" : "is-right"}`}
+							onMouseEnter={() => setHover(rating)}
+							onClick={() => {
+								// Drop the preview with the pick: the pointer is still on this
+								// half, and a preview left up would hide a clear behind the
+								// very stars it just emptied.
+								setHover(null);
+								onChange(rating === value ? null : rating);
+							}}
+						/>
+					))}
+			</span>
+		);
+	});
+
+	if (!onChange) {
+		return (
+			<span
+				role="img"
+				aria-label={`${label}: ${describeStarRating(value)}`}
+				className={classes}
+				style={style}
+			>
+				{stars}
+			</span>
+		);
+	}
+
+	const set = (next: number | null) => {
+		if (next !== value) onChange(next);
+	};
+
+	const onKeyDown = (event: KeyboardEvent) => {
+		const current = value ?? 0;
+		switch (event.key) {
+			case "ArrowRight":
+			case "ArrowUp":
+				set(Math.min(max, current + STEP));
+				break;
+			case "ArrowLeft":
+			case "ArrowDown":
+				set(current - STEP > 0 ? current - STEP : null);
+				break;
+			case "Home":
+				set(null);
+				break;
+			case "End":
+				set(max);
+				break;
+			default:
+				return;
+		}
+		event.preventDefault();
+	};
+
+	return (
+		<span
+			role="slider"
+			tabIndex={0}
+			aria-label={label}
+			aria-valuemin={0}
+			aria-valuemax={max}
+			aria-valuenow={value ?? 0}
+			aria-valuetext={describeStarRating(value)}
+			className={`${classes} is-editable`}
+			style={style}
+			onKeyDown={onKeyDown}
+			onMouseLeave={() => setHover(null)}
+		>
+			{stars}
+		</span>
+	);
+}

package/src/components/index.ts

@@ -18,6 +18,7 @@ export {
 } from "./DataTable";
 export { NotFound, type NotFoundProps } from "./NotFound";
 export { StackedBar, type StackedBarProps, type StackedBarSegment } from "./StackedBar";
+export { describeStarRating, StarRating, type StarRatingProps } from "./StarRating";
 export {
 	type StatDelta,
 	type StatDirection,

package/src/styles/components.css

@@ -1,3 +1,5 @@
+@import "./star-rating.css";
+
 /* Layout defaults for the components under src/components. A site's own
    classes (.page-hero, .eyebrow, .lead, .btn) arrive unlayered and win, so
    these only fill in where a site does not style them. */

package/src/styles/star-rating.css

@@ -0,0 +1,67 @@
+/* StarRating: a row of stars in half star steps. On its own sheet, and not
+   under .mkt, so an app that wears none of the site chrome can import this
+   file alone; components.css imports it for every site.
+
+   The two colors are custom properties with fallbacks off the text color, so
+   the row needs no theme token and takes a color from a prop, from a site's
+   own rule, or from whatever it sits in. */
+@layer atelic-ui {
+	.star-rating {
+		display: inline-flex;
+		align-items: center;
+		vertical-align: middle;
+		line-height: 0;
+		border-radius: 4px;
+	}
+	.star-rating.is-editable:focus-visible {
+		outline: 2px solid var(--star-focus, currentColor);
+		outline-offset: 2px;
+	}
+	.star-rating-star {
+		position: relative;
+		display: inline-block;
+		width: var(--star-size, 24px);
+		height: var(--star-size, 24px);
+	}
+	/* Pinned to the star's size: a base reset that caps an svg at its
+	   container's width would shrink the filled star inside its clip to a
+	   small whole star, where it has to stay full size and be cut in half. */
+	.star-rating .star-rating-star svg {
+		display: block;
+		width: var(--star-size, 24px);
+		height: var(--star-size, 24px);
+		max-width: none;
+	}
+	.star-rating-outline {
+		color: var(--star-outline, color-mix(in srgb, currentColor 40%, transparent));
+	}
+	/* The filled star sits over the outline and is clipped to none, half, or
+	   all of its width. */
+	.star-rating-fill {
+		position: absolute;
+		inset-block: 0;
+		left: 0;
+		overflow: hidden;
+		pointer-events: none;
+		color: var(--star-fill, currentColor);
+	}
+	.star-rating-fill svg {
+		fill: currentColor;
+	}
+	.star-rating-hit {
+		position: absolute;
+		inset-block: 0;
+		width: 50%;
+		margin: 0;
+		padding: 0;
+		border: 0;
+		background: none;
+		cursor: pointer;
+	}
+	.star-rating-hit.is-left {
+		left: 0;
+	}
+	.star-rating-hit.is-right {
+		right: 0;
+	}
+}