@pantoken/react 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @pantoken/react
+
+Thin React helpers over `@pantoken/web-components` and the token CSS: an `<Icon>` component, a
+`useToken` hook, and a `<TokenProvider>` that registers the custom elements client-side.
+
+## Install
+
+```sh
+npm i @pantoken/react
+```
+
+Also available as `pantoken/react`.
+
+## Usage
+
+```tsx
+import { TokenProvider, Icon, useToken } from "@pantoken/react";
+import "@pantoken/css";
+
+function App() {
+  const brand = useToken("--instui-color-background-brand", "#0374B5");
+  return (
+    <TokenProvider>
+      <Icon name="check-mark" size="1.25rem" /> Saved — {brand}
+    </TokenProvider>
+  );
+}
+```
+
+For InstUI's full React component library, use `@instructure/ui-*` directly. This package is the
+lightweight token and icon layer.
+
+## API
+
+- **`<Icon name size? color?>`** — render the `<instui-icon>` custom element (React 19 passes props straight to custom elements).
+- **`<TokenProvider>`** — register the pantoken custom elements client-side, then render children.
+- **`useToken(name, fallback?): string`** — hook returning a resolved `--instui-*` value. Re-reads when `name` changes; SSR-safe.
+- **`readToken(name, fallback?): string`** — read a resolved `--instui-*` value once. Returns `fallback` on the server.
+- **`IconProps`, `TokenProviderProps`** — component prop interfaces.
+- **`register`** — re-exported from `@pantoken/web-components` for direct control over registration timing.
+
+## Related
+
+- Pairs with `@pantoken/css` for the base `--instui-*` custom properties.
+- Wraps `@pantoken/web-components`, which supplies the custom elements.
+
+## License
+
+MIT

package/dist/components.css

@@ -0,0 +1 @@
+.pantoken-prose{color:var(--instui-component-text-base-color);font-family:var(--instui-component-text-content-font-family);font-size:var(--instui-component-text-content-font-size);font-weight:var(--instui-component-text-content-font-weight);line-height:var(--instui-component-text-content-line-height)}.pantoken-prose h1,.pantoken-prose h2,.pantoken-prose h3,.pantoken-prose h4,.pantoken-prose h5,.pantoken-prose h6{color:var(--instui-component-heading-base-color);font-family:var(--instui-component-heading-h1-font-family);line-height:var(--instui-component-heading-line-height);margin:var(--instui-spacing-space-lg) 0 var(--instui-spacing-space-sm)}.pantoken-prose h1{font-size:var(--instui-component-heading-h1-font-size);font-weight:var(--instui-component-heading-h1-font-weight)}.pantoken-prose h2{font-size:var(--instui-component-heading-h2-font-size);font-weight:var(--instui-component-heading-h2-font-weight)}.pantoken-prose h3{font-size:var(--instui-component-heading-h3-font-size);font-weight:var(--instui-component-heading-h3-font-weight)}.pantoken-prose h4{font-size:var(--instui-component-heading-h4-font-size);font-weight:var(--instui-component-heading-h4-font-weight)}.pantoken-prose h5{font-size:var(--instui-component-heading-h5-font-size);font-weight:var(--instui-component-heading-h5-font-weight)}.pantoken-prose h6{font-size:var(--instui-component-heading-h6-font-size);font-weight:var(--instui-component-heading-h6-font-weight)}.pantoken-prose p{margin:var(--instui-spacing-space-md) 0}.pantoken-prose a{color:var(--instui-color-text-interactive-navigation-primary-base);text-decoration:underline}.pantoken-prose a:hover{color:var(--instui-color-text-interactive-navigation-primary-hover)}.pantoken-prose strong,.pantoken-prose b{font-weight:var(--instui-component-text-content-important-font-weight)}.pantoken-prose em,.pantoken-prose i{font-style:italic}.pantoken-prose small{font-size:var(--instui-component-text-content-small-font-size)}.pantoken-prose del,.pantoken-prose s{color:var(--instui-color-text-muted);text-decoration:line-through}.pantoken-prose ul,.pantoken-prose ol{margin:var(--instui-spacing-space-md) 0;padding-inline-start:var(--instui-spacing-space-lg)}.pantoken-prose li{margin:var(--instui-spacing-space2xs) 0}.pantoken-prose li.task-list-item{list-style:none}.pantoken-prose input[type=checkbox]{accent-color:var(--instui-color-text-interactive-navigation-primary-base);margin-inline-end:var(--instui-spacing-space-xs)}.pantoken-prose blockquote{margin:var(--instui-spacing-space-md) 0;border-inline-start:var(--instui-border-width-lg) solid var(--instui-color-stroke-base);color:var(--instui-component-text-base-color);font-size:var(--instui-component-text-content-quote-font-size);line-height:var(--instui-component-text-content-quote-line-height);padding-inline-start:var(--instui-spacing-space-md)}.pantoken-prose code{font-family:var(--instui-font-family-code);background:var(--instui-color-background-muted);padding:var(--instui-spacing-space2xs) var(--instui-spacing-space-xs);border-radius:var(--instui-border-radius-sm);font-size:.9em}.pantoken-prose pre{font-family:var(--instui-font-family-code);background:var(--instui-color-background-container);color:var(--instui-color-text-base);padding:var(--instui-spacing-space-md);border:var(--instui-border-width-sm) solid var(--instui-color-stroke-base);border-radius:var(--instui-border-radius-md);overflow-x:auto}.pantoken-prose pre code{font-size:inherit;background:0 0;border-radius:0;padding:0}.pantoken-prose hr{border:none;border-top:var(--instui-border-width-sm) solid var(--instui-color-stroke-base);margin:var(--instui-spacing-space-lg) 0}.pantoken-prose img{border-radius:var(--instui-border-radius-md);max-width:100%}.pantoken-prose table:not([class]){border-collapse:collapse;width:100%;margin:var(--instui-spacing-space-md) 0;background:var(--instui-component-table-background);color:var(--instui-component-table-color);font-family:var(--instui-component-table-font-family);font-size:var(--instui-component-table-font-size)}.pantoken-prose table:not([class]) th{text-align:start;background:var(--instui-component-table-col-header-background);color:var(--instui-component-table-col-header-color);font-weight:var(--instui-component-table-head-font-weight);padding:var(--instui-component-table-col-header-padding-vertical) var(--instui-component-table-col-header-padding-horizontal);border-bottom:var(--instui-border-width-md) solid var(--instui-component-table-row-border-color)}.pantoken-prose table:not([class]) td{color:var(--instui-component-table-cell-color);line-height:var(--instui-component-table-cell-line-height);padding:var(--instui-component-table-cell-padding-vertical) var(--instui-component-table-cell-padding-horizontal);border-bottom:var(--instui-border-width-sm) solid var(--instui-component-table-row-border-color)}

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+import { register } from "@pantoken/web-components";
+import { ReactNode } from "react";
+
+//#region src/index.d.ts
+/**
+ * Read a resolved token value from the document. Returns `fallback` on the server.
+ *
+ * @example
+ * ```tsx
+ * import { readToken } from "@pantoken/react";
+ *
+ * const brand = readToken("--instui-color-background-brand", "#0374B5");
+ * ```
+ */
+declare function readToken(name: string, fallback?: string): string;
+/**
+ * React hook returning a resolved `--instui-*` token value (re-reads on `name` change).
+ *
+ * @example
+ * ```tsx
+ * import { useToken } from "@pantoken/react";
+ *
+ * function Banner() {
+ *   const brand = useToken("--instui-color-background-brand", "#0374B5");
+ *   return <div style={{ background: brand }}>Saved</div>;
+ * }
+ * ```
+ */
+declare function useToken(name: string, fallback?: string): string;
+/** Props for {@link Icon}. */
+interface IconProps {
+  name: string;
+  size?: string;
+  color?: string;
+}
+/**
+ * Render an Instructure icon as the `<instui-icon>` custom element.
+ *
+ * @example
+ * ```tsx
+ * import { Icon } from "@pantoken/react";
+ *
+ * <Icon name="check-mark" size="1.25rem" color="var(--instui-color-text-success)" />;
+ * ```
+ */
+declare function Icon({
+  name,
+  size,
+  color
+}: IconProps): ReactNode;
+/** Props for {@link TokenProvider}. */
+interface TokenProviderProps {
+  children?: ReactNode;
+}
+/**
+ * Register the pantoken custom elements (client-side) and render children.
+ *
+ * @example
+ * ```tsx
+ * import { TokenProvider, Icon } from "@pantoken/react";
+ * import "@pantoken/css";
+ *
+ * function App() {
+ *   return (
+ *     <TokenProvider>
+ *       <Icon name="check-mark" size="1.25rem" /> Saved
+ *     </TokenProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function TokenProvider({
+  children
+}: TokenProviderProps): ReactNode;
+//#endregion
+export { Icon, IconProps, TokenProvider, TokenProviderProps, readToken, register, useToken };

package/dist/index.mjs

@@ -0,0 +1,90 @@
+import { register, register as register$1 } from "@pantoken/web-components";
+import { createElement, useEffect, useState } from "react";
+//#region src/index.tsx
+/**
+* `@pantoken/react` — thin React helpers over `@pantoken/web-components` and the token CSS.
+*
+* - `<Icon>` renders the `<instui-icon>` custom element (React 19 passes props to custom elements).
+* - `useToken` reads a resolved `--instui-*` value at runtime (SSR-safe: returns the fallback on
+*   the server).
+* - `<TokenProvider>` registers the elements and is where an app can inject the stylesheet.
+*
+* @module
+* @experimental
+*/
+/**
+* Read a resolved token value from the document. Returns `fallback` on the server.
+*
+* @example
+* ```tsx
+* import { readToken } from "@pantoken/react";
+*
+* const brand = readToken("--instui-color-background-brand", "#0374B5");
+* ```
+*/
+function readToken(name, fallback = "") {
+	if (typeof window === "undefined" || typeof document === "undefined") return fallback;
+	return getComputedStyle(document.documentElement).getPropertyValue(name).trim() || fallback;
+}
+/**
+* React hook returning a resolved `--instui-*` token value (re-reads on `name` change).
+*
+* @example
+* ```tsx
+* import { useToken } from "@pantoken/react";
+*
+* function Banner() {
+*   const brand = useToken("--instui-color-background-brand", "#0374B5");
+*   return <div style={{ background: brand }}>Saved</div>;
+* }
+* ```
+*/
+function useToken(name, fallback = "") {
+	const [value, setValue] = useState(fallback);
+	useEffect(() => {
+		setValue(readToken(name, fallback));
+	}, [name, fallback]);
+	return value;
+}
+/**
+* Render an Instructure icon as the `<instui-icon>` custom element.
+*
+* @example
+* ```tsx
+* import { Icon } from "@pantoken/react";
+*
+* <Icon name="check-mark" size="1.25rem" color="var(--instui-color-text-success)" />;
+* ```
+*/
+function Icon({ name, size, color }) {
+	return createElement("instui-icon", {
+		name,
+		size,
+		color
+	});
+}
+/**
+* Register the pantoken custom elements (client-side) and render children.
+*
+* @example
+* ```tsx
+* import { TokenProvider, Icon } from "@pantoken/react";
+* import "@pantoken/css";
+*
+* function App() {
+*   return (
+*     <TokenProvider>
+*       <Icon name="check-mark" size="1.25rem" /> Saved
+*     </TokenProvider>
+*   );
+* }
+* ```
+*/
+function TokenProvider({ children }) {
+	useEffect(() => {
+		register$1();
+	}, []);
+	return children ?? null;
+}
+//#endregion
+export { Icon, TokenProvider, readToken, register, useToken };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pantoken/react",
+  "version": "0.1.0",
+  "description": "React helpers for pantoken: <Icon>, useToken, and TokenProvider over the web components + token CSS.",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./components.css": "./dist/components.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pantoken/web-components": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4",
+    "@pantoken/components": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "pantoken": {
+    "key": "react",
+    "kind": "subpath"
+  },
+  "scripts": {
+    "generate": "node scripts/generate.ts",
+    "build": "vp run generate && vp pack",
+    "dev": "vp run generate && vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}