margo-ui 1.2.3 → 1.2.4

package/README.md

@@ -1,8 +1,8 @@
 # margo-ui
 
-A small React UI kit built on Tailwind CSS v4 design tokens..
+A small React UI kit built on Tailwind CSS v4 design tokens, themeable through plain CSS custom properties.
 
-The package is published as TypeScript source: your bundler compiles it, exactly as it already has to scan it for Tailwind classes.
+Documentation: [dev.robertoattanasio.com/margo-ui](https://dev.robertoattanasio.com/margo-ui)
 
 ## Install
 
@@ -10,8 +10,6 @@ The package is published as TypeScript source: your bundler compiles it, exactly
 npm install margo-ui
 ```
 
-## Getting started
-
 ```css
 /* your entry stylesheet */
 @import "tailwindcss";
@@ -20,6 +18,24 @@ npm install margo-ui
 @import "margo-ui/css";
 ```
 
+Order matters: `tailwindcss` first, the kit after, your own overrides last. The font imports are optional.
+
+## Built with
+
+React 19, Tailwind CSS v4, TypeScript. [react-renderable](https://www.npmjs.com/package/react-renderable) for polymorphic rendering, clsx and tailwind-merge for class resolution, react-icons for the few built-in glyphs. Nunito and Bebas Neue are bundled as self-hosted woff2.
+
+The package is published as TypeScript source: your bundler compiles it, exactly as it already has to scan it for Tailwind classes.
+
+## Approach
+
+- **Tokens, not props.** Every visual decision is a `--margo-` custom property, mirrored into Tailwind's theme. Theming means redeclaring variables, never overriding classes.
+- **CSS first.** Effects live on pseudo-elements; JavaScript only writes coordinates. Most components hold no state.
+- **Polymorphic.** `as` chooses the rendered element, and the remaining props are typed against it.
+- **Composed, not configured.** Components expose parts to mount rather than booleans to set.
+- **The consumer owns the layout.** Components style themselves and never their position.
+
+Conventions for contributing: [RULE.md](./RULE.md).
+
 ## License
 
 Code: [MIT](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "margo-ui",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "A small React UI kit built on Tailwind CSS v4 design tokens, themeable through plain CSS custom properties.",
   "keywords": [
     "react",
@@ -12,6 +12,15 @@
   ],
   "license": "MIT",
   "author": "Roberto Attanasio",
+  "homepage": "https://dev.robertoattanasio.com/margo-ui",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robertoattanasio/dev.robertoattanasio.com.git",
+    "directory": "lib/margo-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/robertoattanasio/dev.robertoattanasio.com/issues"
+  },
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -42,6 +51,7 @@
   },
   "dependencies": {
     "clsx": "^2.1.1",
+    "react-icons": "^5.7.0",
     "react-renderable": "^1.0.4",
     "tailwind-merge": "^3.6.0"
   },

package/src/components/button/button.tsx

@@ -39,7 +39,7 @@ export const Button = <T extends ElementType = "button">({
     <Ripple>
       <Tag
         {...Tag.forward<T>(rest, "button")}
-        data-open={open}
+        data-margo-open={open}
         onClick={handleClick}
         className={cn(
           buttonBaseClassName,
@@ -52,11 +52,11 @@ export const Button = <T extends ElementType = "button">({
   );
 };
 
-Button.Icon = ({ icon, className = null }: ButtonIconProps) => (
+Button.Icon = ({ icon, className }: ButtonIconProps) => (
   <span className={cn(buttonIconClassName, className)}>{icon}</span>
 );
 
-Button.Label = ({ label, className = null }: ButtonLabelProps) => (
+Button.Label = ({ label, className }: ButtonLabelProps) => (
   <span className={cn(buttonLabelClassName, className)}>{label}</span>
 );
 
@@ -66,7 +66,7 @@ Button.IconLabel = ({
   gap = "0.5rem",
   reverse = false,
   side = "end",
-  className = null,
+  className,
 }: ButtonIconLabelProps) => (
   <span
     style={{ "--button-gap": gap } as CSSProperties}

package/src/components/button/style.ts

@@ -17,11 +17,11 @@ export const buttonGridClassName =
 
 export const buttonGridForwardClassName = `grid-cols-[1rem_0fr] group-hover/button:grid-cols-[1rem_1fr] group-hover/button:gap-(--button-gap)
 group-focus-visible/button:grid-cols-[1rem_1fr] group-focus-visible/button:gap-(--button-gap)
-group-data-[open=true]/button:grid-cols-[1rem_1fr] group-data-[open=true]/button:gap-(--button-gap)`;
+group-data-[margo-open=true]/button:grid-cols-[1rem_1fr] group-data-[margo-open=true]/button:gap-(--button-gap)`;
 
 export const buttonGridReverseClassName = `grid-cols-[auto_0rem] group-hover/button:grid-cols-[auto_1rem] group-hover/button:gap-(--button-gap)
 group-focus-visible/button:grid-cols-[auto_1rem] group-focus-visible/button:gap-(--button-gap)
-group-data-[open=true]/button:grid-cols-[auto_1rem] group-data-[open=true]/button:gap-(--button-gap)`;
+group-data-[margo-open=true]/button:grid-cols-[auto_1rem] group-data-[margo-open=true]/button:gap-(--button-gap)`;
 
 export const buttonSlotClassName = `min-w-0 overflow-hidden opacity-0 transition-opacity duration-[180ms] ease-in
-group-hover/button:opacity-100 group-focus-visible/button:opacity-100 group-data-[open=true]/button:opacity-100`;
+group-hover/button:opacity-100 group-focus-visible/button:opacity-100 group-data-[margo-open=true]/button:opacity-100`;

package/src/components/button/type.ts

@@ -15,12 +15,12 @@ export type ButtonProps<T extends ElementType = "button"> = TagProps<T, ButtonOw
 
 export type ButtonIconProps = {
   icon: ReactNode;
-  className?: string | null;
+  className?: string;
 };
 
 export type ButtonLabelProps = {
   label: string;
-  className?: string | null;
+  className?: string;
 };
 
 export type ButtonIconLabelProps = {
@@ -29,5 +29,5 @@ export type ButtonIconLabelProps = {
   gap?: string;
   reverse?: boolean;
   side?: ButtonIconLabelSide;
-  className?: string | null;
+  className?: string;
 };

package/src/components/item/item.tsx

@@ -0,0 +1,57 @@
+import { MdChevronRight } from "react-icons/md";
+
+import { Tag } from "react-renderable";
+
+import { cn } from "../../utils/cn/cn.js";
+import {
+  itemActiveClassName,
+  itemBaseClassName,
+  itemIconClassName,
+  itemLabelClassName,
+  itemSurfaceClassName,
+} from "./style.js";
+
+import type { ElementType, MouseEvent } from "react";
+import { Ripple } from "../../hoc/ripple/ripple.js";
+import type { ItemIconProps, ItemLabelProps, ItemProps } from "./type.js";
+
+export const Item = <T extends ElementType = "div">({
+  active = false,
+  onClickBlur,
+  onClick,
+  className,
+  children,
+  ...rest
+}: ItemProps<T>) => {
+  const handleClick = (event: MouseEvent<HTMLElement>) => {
+    onClick?.(event);
+    if (typeof onClickBlur === "function") {
+      const target = event.currentTarget;
+      onClickBlur(event);
+      setTimeout(() => target.blur(), 150);
+    }
+  };
+
+  return (
+    <Ripple>
+      <Tag
+        {...Tag.forward<T>(rest)}
+        data-margo-active={active}
+        onClick={handleClick}
+        className={cn(itemBaseClassName, active ? itemActiveClassName : itemSurfaceClassName, className)}
+      >
+        {children}
+      </Tag>
+    </Ripple>
+  );
+};
+
+Item.Icon = ({ icon = <MdChevronRight className="text-md translate-x-1" />, className }: ItemIconProps) => (
+  <span data-margo-item-slot={true} className={cn(itemIconClassName, className)}>
+    {icon}
+  </span>
+);
+
+Item.Label = ({ label, className }: ItemLabelProps) => (
+  <span className={cn(itemLabelClassName, className)}>{label}</span>
+);

package/src/components/item/style.ts

@@ -0,0 +1,13 @@
+export const itemBaseClassName = `group/item flex w-full items-center gap-1 rounded-lg border-2 px-3 py-2 text-on-main
+text-sm focus-visible:margo-border-gradient-primary focus-visible:outline
+focus-visible:outline-offset-1 focus-visible:outline-on-main`;
+
+export const itemSurfaceClassName = `border-transparent text-medium hover:border-border hover:text-on-main
+hover:shadow-item focus-visible:shadow-item`;
+
+export const itemActiveClassName = "margo-border-gradient-primary text-on-main shadow-item";
+
+export const itemIconClassName = `ml-auto flex size-4 shrink-0 items-center justify-center
+[[data-margo-item-slot]+&]:ml-0`;
+
+export const itemLabelClassName = "min-w-0 truncate text-left";

package/src/components/item/type.ts

@@ -0,0 +1,20 @@
+import type { TagProps } from "react-renderable";
+import type { ElementType, MouseEventHandler, ReactNode } from "react";
+
+export type ItemOwnProps = {
+  active?: boolean;
+  onClick?: MouseEventHandler<HTMLElement>;
+  onClickBlur?: MouseEventHandler<HTMLElement>;
+};
+
+export type ItemProps<T extends ElementType = "div"> = TagProps<T, ItemOwnProps>;
+
+export type ItemIconProps = {
+  icon?: ReactNode;
+  className?: string;
+};
+
+export type ItemLabelProps = {
+  label: ReactNode;
+  className?: string;
+};

package/src/components/navigation_bar/navigation_bar.css

@@ -0,0 +1,21 @@
+.margo-navigation-bar {
+  position: relative;
+  height: 100%;
+  width: var(--margo-navigation-bar-progress, 0%);
+  background: var(--margo-navigation-bar-fill);
+  transition: width 200ms ease-out;
+}
+
+.margo-navigation-bar::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  right: 0;
+  height: 100%;
+  width: 6.25rem;
+  transform: rotate(3deg) translateY(-0.25rem);
+  opacity: 0.9;
+  box-shadow:
+    0 0 10px var(--margo-color-primary),
+    0 0 5px var(--margo-color-primary);
+}

package/src/components/navigation_bar/navigation_bar.tsx

@@ -0,0 +1,63 @@
+import { useEffect, useRef, useState } from "react";
+
+import { Tag } from "react-renderable";
+
+import { cn } from "../../utils/cn/cn.js";
+import { navigationBarDefaultFill, navigationBarBaseClassName, navigationBarTrackClassName } from "./style.js";
+
+import type { CSSProperties, ElementType } from "react";
+import type { NavigationBarProps } from "./type.js";
+
+import "./navigation_bar.css";
+
+const TRICKLE_MS = 200;
+const TRICKLE_CEILING = 90;
+const TRICKLE_RATIO = 0.12;
+const START_PROGRESS = 8;
+const FADE_MS = 250;
+
+export const NavigationBar = <T extends ElementType = "div">({
+  loading = false,
+  fill = navigationBarDefaultFill,
+  className,
+  ...rest
+}: NavigationBarProps<T>) => {
+  const [progress, setProgress] = useState(0);
+  const [isVisible, setIsVisible] = useState(false);
+  const timeoutRef = useRef<number | undefined>(undefined);
+
+  useEffect(() => {
+    if (loading) {
+      window.clearTimeout(timeoutRef.current);
+      setIsVisible(true);
+      setProgress(START_PROGRESS);
+
+      const interval = window.setInterval(
+        () => setProgress((current) => current + (TRICKLE_CEILING - current) * TRICKLE_RATIO),
+        TRICKLE_MS,
+      );
+
+      return () => window.clearInterval(interval);
+    }
+
+    setProgress((current) => (current > 0 ? 100 : 0));
+    timeoutRef.current = window.setTimeout(() => {
+      setIsVisible(false);
+      setProgress(0);
+    }, FADE_MS);
+
+    return () => window.clearTimeout(timeoutRef.current);
+  }, [loading]);
+
+  return (
+    <Tag
+      {...Tag.forward<T>(rest)}
+      role="progressbar"
+      aria-hidden={!isVisible}
+      style={{ "--margo-navigation-bar-fill": fill, "--margo-navigation-bar-progress": `${progress}%` } as CSSProperties}
+      className={cn(navigationBarBaseClassName, isVisible ? "opacity-100" : "opacity-0", className)}
+    >
+      <div className={navigationBarTrackClassName} />
+    </Tag>
+  );
+};

package/src/components/navigation_bar/style.ts

@@ -0,0 +1,6 @@
+export const navigationBarDefaultFill = "linear-gradient(to right, var(--margo-color-primary-darken), var(--margo-color-primary))";
+
+export const navigationBarBaseClassName =
+  "fixed inset-x-0 top-0 z-max h-0.5 pointer-events-none transition-opacity duration-200 ease-out";
+
+export const navigationBarTrackClassName = "margo-navigation-bar";

package/src/components/navigation_bar/type.ts

@@ -0,0 +1,9 @@
+import type { TagProps } from "react-renderable";
+import type { ElementType } from "react";
+
+export type NavigationBarOwnProps = {
+  loading?: boolean;
+  fill?: string;
+};
+
+export type NavigationBarProps<T extends ElementType = "div"> = TagProps<T, NavigationBarOwnProps>;

package/src/components/progress_bar/progress_bar.css

@@ -2,21 +2,18 @@
   content: "";
   position: absolute;
   inset: 0;
-  background: var(
-    --margo-progress-bar-fill,
-    linear-gradient(to right, var(--color-primary-darken), var(--color-primary))
-  );
+  background: var(--margo-progress-bar-fill);
 }
 
-.margo-progress-bar[data-mode="determinate"]::before {
+.margo-progress-bar[data-margo-mode="determinate"]::before {
   clip-path: inset(0 calc(100% - var(--margo-progress-bar-value, 0%)) 0 0);
 }
 
-.margo-progress-bar[data-mode="determinate"][data-animate="true"]::before {
+.margo-progress-bar[data-margo-mode="determinate"][data-margo-animate="true"]::before {
   transition: clip-path 300ms ease-out;
 }
 
-.margo-progress-bar[data-mode="indeterminate"]::before {
+.margo-progress-bar[data-margo-mode="indeterminate"]::before {
   inset: 0 auto 0 0;
   width: 50%;
   animation: margo-progress-bar-indeterminate 800ms ease-in-out infinite;

package/src/components/progress_bar/progress_bar.tsx

@@ -1,7 +1,7 @@
 import { Tag } from "react-renderable";
 
 import { cn } from "../../utils/cn/cn.js";
-import { progressBarBaseClassName } from "./style.js";
+import { progressBarDefaultFill, progressBarBaseClassName } from "./style.js";
 
 import type { CSSProperties, ElementType } from "react";
 import type { ProgressBarProps } from "./type.js";
@@ -10,6 +10,7 @@ import "./progress_bar.css";
 
 export const ProgressBar = <T extends ElementType = "div">({
   animate = true,
+  fill = progressBarDefaultFill,
   mode = "indeterminate",
   style,
   value = 0,
@@ -26,9 +27,11 @@ export const ProgressBar = <T extends ElementType = "div">({
       aria-valuemin={isDeterminate ? 0 : undefined}
       aria-valuemax={isDeterminate ? 100 : undefined}
       aria-valuenow={isDeterminate ? progress : undefined}
-      data-mode={mode}
-      data-animate={animate}
-      style={{ ...style, "--margo-progress-bar-value": `${progress}%` } as CSSProperties}
+      data-margo-mode={mode}
+      data-margo-animate={animate}
+      style={
+        { ...style, "--margo-progress-bar-fill": fill, "--margo-progress-bar-value": `${progress}%` } as CSSProperties
+      }
       className={cn(progressBarBaseClassName, className)}
     />
   );

package/src/components/progress_bar/style.ts

@@ -1 +1,3 @@
+export const progressBarDefaultFill = "linear-gradient(to right, var(--margo-color-primary-darken), var(--margo-color-primary))";
+
 export const progressBarBaseClassName = "margo-progress-bar relative h-0.5 overflow-hidden";

package/src/components/progress_bar/type.ts

@@ -5,6 +5,7 @@ export type ProgressBarMode = "determinate" | "indeterminate";
 
 export type ProgressBarOwnProps = {
   animate?: boolean;
+  fill?: string;
   mode?: ProgressBarMode;
   value?: number;
 };

package/src/components/snippet/highlight.ts

@@ -0,0 +1,83 @@
+import type { SnippetToken, SnippetTokenType } from "./type.js";
+
+const KEYWORDS = [
+  "as",
+  "async",
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "export",
+  "extends",
+  "false",
+  "for",
+  "from",
+  "function",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "interface",
+  "let",
+  "new",
+  "null",
+  "of",
+  "readonly",
+  "return",
+  "satisfies",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "type",
+  "typeof",
+  "undefined",
+  "var",
+  "void",
+  "while",
+  "yield",
+];
+
+const PATTERNS: readonly { type: SnippetTokenType; source: string }[] = [
+  { type: "comment", source: "\\/\\/[^\\n]*|\\/\\*[\\s\\S]*?\\*\\/" },
+  { type: "string", source: "\"(?:[^\"\\\\]|\\\\.)*\"|'(?:[^'\\\\]|\\\\.)*'|`(?:[^`\\\\]|\\\\.)*`" },
+  { type: "tag", source: "<\\/?[A-Za-z][\\w.$]*" },
+  { type: "keyword", source: `\\b(?:${KEYWORDS.join("|")})\\b` },
+  { type: "number", source: "\\b\\d+(?:\\.\\d+)?\\b" },
+  { type: "attr", source: "\\b[A-Za-z_$][\\w$]*(?=\\s*[=:](?!=))" },
+  { type: "fn", source: "\\b[A-Za-z_$][\\w$]*(?=\\s*\\()" },
+  { type: "type", source: "\\b[A-Z][\\w$]*\\b" },
+  { type: "punct", source: "[{}()\\[\\]<>=;,.:!?|&+\\-*/]" },
+];
+
+const TOKENIZER = new RegExp(PATTERNS.map((pattern) => `(${pattern.source})`).join("|"), "g");
+
+export const snippetHighlight = (code: string): SnippetToken[] => {
+  const tokens: SnippetToken[] = [];
+  let cursor = 0;
+  let match: RegExpExecArray | null;
+
+  TOKENIZER.lastIndex = 0;
+
+  while ((match = TOKENIZER.exec(code)) !== null) {
+    if (match.index > cursor) tokens.push({ type: "plain", value: code.slice(cursor, match.index) });
+
+    const groupIndex = PATTERNS.findIndex((_, index) => match![index + 1] !== undefined);
+
+    tokens.push({ type: PATTERNS[groupIndex].type, value: match[0] });
+    cursor = match.index + match[0].length;
+  }
+
+  if (cursor < code.length) tokens.push({ type: "plain", value: code.slice(cursor) });
+
+  return tokens;
+};

package/src/components/snippet/snippet.tsx

@@ -0,0 +1,63 @@
+import { useState } from "react";
+
+import { MdCheck, MdContentCopy } from "react-icons/md";
+
+import { Guard, List, Swap, Tag } from "react-renderable";
+
+import { cn } from "../../utils/cn/cn.js";
+import { Button } from "../button/button.js";
+import { snippetHighlight } from "./highlight.js";
+import {
+  snippetBarClassName,
+  snippetBaseClassName,
+  snippetCodeClassName,
+  snippetCopyClassName,
+  snippetTitleClassName,
+  snippetTokenClassName,
+} from "./style.js";
+
+import type { ElementType } from "react";
+import type { SnippetProps } from "./type.js";
+
+export const Snippet = <T extends ElementType = "div">({ snippet, title, className, ...rest }: SnippetProps<T>) => {
+  const [isCopied, setIsCopied] = useState(false);
+  const source = snippet.trim();
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(source);
+    setIsCopied(true);
+    window.setTimeout(() => setIsCopied(false), 1500);
+  };
+
+  return (
+    <Tag {...Tag.forward<T>(rest)} className={cn(snippetBaseClassName, className)}>
+      <div className={snippetBarClassName}>
+        <Guard guardIf={!title} shouldHide>
+          <span className={snippetTitleClassName}>{title}</span>
+        </Guard>
+        <Button onClickBlur={handleCopy} aria-label="copy" aria-pressed={isCopied} className={snippetCopyClassName}>
+          <Button.Icon
+            icon={
+              <Swap.Boolean
+                swapOn={isCopied}
+                components={[<MdContentCopy className="text-sm" />, <MdCheck className="text-sm" />]}
+              />
+            }
+          />
+        </Button>
+      </div>
+      <pre className={snippetCodeClassName}>
+        <code>
+          <List
+            array={snippetHighlight(source)}
+            itemExtractor={({ row, index }) => (
+              <span key={index} className={snippetTokenClassName[row.type]}>
+                {row.value}
+              </span>
+            )}
+          />
+        </code>
+      </pre>
+    </Tag>
+  );
+};

package/src/components/snippet/style.ts

@@ -0,0 +1,25 @@
+import type { SnippetTokenType } from "./type.js";
+
+export const snippetBaseClassName = "overflow-hidden rounded-lg border-2 border-border bg-(--margo-code-surface)";
+
+export const snippetBarClassName =
+  "flex items-center justify-between gap-4 border-b-2 border-border bg-(--margo-code-bar) px-3 py-2";
+
+export const snippetTitleClassName = "text-mc uppercase tracking-widest text-medium";
+
+export const snippetCopyClassName = "ml-auto bg-neutral/60";
+
+export const snippetCodeClassName = "overflow-x-auto p-4 text-xs leading-relaxed";
+
+export const snippetTokenClassName: Record<SnippetTokenType, string> = {
+  plain: "text-(--margo-code-plain)",
+  comment: "text-(--margo-code-comment) italic",
+  string: "text-(--margo-code-string)",
+  keyword: "text-(--margo-code-keyword)",
+  number: "text-(--margo-code-number)",
+  tag: "text-(--margo-code-tag)",
+  attr: "text-(--margo-code-attr)",
+  fn: "text-(--margo-code-fn)",
+  type: "text-(--margo-code-type)",
+  punct: "text-(--margo-code-punct)",
+};

package/src/components/snippet/type.ts

@@ -0,0 +1,26 @@
+import type { TagProps } from "react-renderable";
+import type { ElementType } from "react";
+
+export type SnippetTokenType =
+  | "plain"
+  | "comment"
+  | "string"
+  | "keyword"
+  | "number"
+  | "tag"
+  | "attr"
+  | "fn"
+  | "type"
+  | "punct";
+
+export type SnippetToken = {
+  type: SnippetTokenType;
+  value: string;
+};
+
+export type SnippetOwnProps = {
+  snippet: string;
+  title?: string;
+};
+
+export type SnippetProps<T extends ElementType = "div"> = TagProps<T, SnippetOwnProps>;

package/src/components/table/style.ts

@@ -0,0 +1,13 @@
+export const tableWrapperClassName = "w-full overflow-x-auto rounded-lg border-2 border-border";
+
+export const tableBaseClassName = "w-full border-collapse text-xs text-on-main";
+
+export const tableHeadClassName = "border-b-2 border-border bg-neutral/40 text-left";
+
+export const tableBodyClassName = "align-top";
+
+export const tableRowClassName = "border-b-2 border-border last:border-b-0";
+
+export const tableHeadCellClassName = "px-3 py-2 font-medium whitespace-nowrap";
+
+export const tableCellClassName = "px-3 py-2 align-top whitespace-nowrap";

package/src/components/table/table.tsx

@@ -0,0 +1,60 @@
+import { Tag } from "react-renderable";
+
+import { cn } from "../../utils/cn/cn.js";
+import {
+  tableBaseClassName,
+  tableBodyClassName,
+  tableCellClassName,
+  tableHeadCellClassName,
+  tableHeadClassName,
+  tableRowClassName,
+  tableWrapperClassName,
+} from "./style.js";
+
+import type { ElementType } from "react";
+import type {
+  TableBodyProps,
+  TableCellProps,
+  TableHeadCellProps,
+  TableHeadProps,
+  TableProps,
+  TableRowProps,
+} from "./type.js";
+
+export const Table = <T extends ElementType = "table">({ className, children, ...rest }: TableProps<T>) => (
+  <div className={tableWrapperClassName}>
+    <Tag {...Tag.forward<T>(rest, "table")} className={cn(tableBaseClassName, className)}>
+      {children}
+    </Tag>
+  </div>
+);
+
+Table.Head = <T extends ElementType = "thead">({ className, children, ...rest }: TableHeadProps<T>) => (
+  <Tag {...Tag.forward<T>(rest, "thead")} className={cn(tableHeadClassName, className)}>
+    {children}
+  </Tag>
+);
+
+Table.Body = <T extends ElementType = "tbody">({ className, children, ...rest }: TableBodyProps<T>) => (
+  <Tag {...Tag.forward<T>(rest, "tbody")} className={cn(tableBodyClassName, className)}>
+    {children}
+  </Tag>
+);
+
+Table.Row = <T extends ElementType = "tr">({ className, children, ...rest }: TableRowProps<T>) => (
+  <Tag {...Tag.forward<T>(rest, "tr")} className={cn(tableRowClassName, className)}>
+    {children}
+  </Tag>
+);
+
+Table.HeadCell = <T extends ElementType = "th">({ className, children, ...rest }: TableHeadCellProps<T>) => (
+  <Tag {...Tag.forward<T>(rest, "th")} className={cn(tableHeadCellClassName, className)}>
+    {children}
+  </Tag>
+);
+
+Table.Cell = <T extends ElementType = "td">({ className, children, ...rest }: TableCellProps<T>) => (
+  <Tag {...Tag.forward<T>(rest, "td")} className={cn(tableCellClassName, className)}>
+    {children}
+  </Tag>
+);

package/src/components/table/type.ts

@@ -0,0 +1,14 @@
+import type { TagProps } from "react-renderable";
+import type { ElementType } from "react";
+
+export type TableProps<T extends ElementType = "table"> = TagProps<T>;
+
+export type TableHeadProps<T extends ElementType = "thead"> = TagProps<T>;
+
+export type TableBodyProps<T extends ElementType = "tbody"> = TagProps<T>;
+
+export type TableRowProps<T extends ElementType = "tr"> = TagProps<T>;
+
+export type TableHeadCellProps<T extends ElementType = "th"> = TagProps<T>;
+
+export type TableCellProps<T extends ElementType = "td"> = TagProps<T>;

package/src/components/tooltip/tooltip.tsx

@@ -15,19 +15,19 @@ import type { ElementType, ReactNode } from "react";
 import type { TooltipProps } from "./type.js";
 
 export const Tooltip = <T extends ElementType = "div">({
-  ariaLabel,
+  label,
   children,
   className,
   id,
-  placeholder,
+  content,
   position = "down",
   ...rest
 }: TooltipProps<T>) => {
-  const placeholderRef = useRef<ReactNode>(null);
+  const contentRef = useRef<ReactNode>(null);
 
-  const isFilled = placeholder !== null && placeholder !== undefined;
+  const isFilled = content !== null && content !== undefined;
 
-  if (isFilled) placeholderRef.current = placeholder;
+  if (isFilled) contentRef.current = content;
 
   return (
     <Tag {...Tag.forward<T>(rest)} className={cn(tooltipAnchorClassName, className)}>
@@ -35,7 +35,7 @@ export const Tooltip = <T extends ElementType = "div">({
       <span
         id={id}
         role="tooltip"
-        aria-label={isFilled ? undefined : ariaLabel}
+        aria-label={isFilled ? undefined : label}
         className={cn(
           tooltipBubbleClassName,
           tooltipTransitionClassName,
@@ -43,7 +43,7 @@ export const Tooltip = <T extends ElementType = "div">({
           tooltipPositionClassName[position],
         )}
       >
-        {placeholderRef.current}
+        {contentRef.current}
       </span>
     </Tag>
   );

package/src/components/tooltip/type.ts

@@ -4,9 +4,9 @@ import type { ElementType, ReactNode } from "react";
 export type TooltipPosition = "up" | "down" | "left" | "right";
 
 export type TooltipOwnProps = {
-  ariaLabel?: string;
+  label?: string;
   id?: string;
-  placeholder?: ReactNode;
+  content?: ReactNode;
   position?: TooltipPosition;
   children?: ReactNode;
 };

package/src/css/grid.css

@@ -88,6 +88,26 @@
   margin-inline: calc(var(--margo-grid-bleed) * -1);
 }
 
+/*
+ * Bleed padding: the exact counterpart of the bleed margins above. An element
+ * that bled off an edge gets its content back on the grid by padding it by the
+ * same distance, so the background reaches the viewport while the text stays
+ * aligned with the columns.
+ *
+ * Use on: a bled sidebar, band or bar whose children must keep the alignment.
+ */
+@utility margo-pl-bleed {
+  padding-inline-start: var(--margo-grid-bleed);
+}
+
+@utility margo-pr-bleed {
+  padding-inline-end: var(--margo-grid-bleed);
+}
+
+@utility margo-px-bleed {
+  padding-inline: var(--margo-grid-bleed);
+}
+
 /*
  * Back to the centered content area (all 12 columns), dropping any bleed.
  * Use to reset an element that a variant put on `full` at another breakpoint.

package/src/css/theme.css

@@ -26,6 +26,7 @@
   /* Shadows */
   --shadow-card: var(--margo-shadow-card);
   --shadow-button: var(--margo-shadow-button);
+  --shadow-item: var(--margo-shadow-item);
   --shadow-chip: var(--margo-shadow-chip);
 
   /* Border widths */

package/src/css/variables.css

@@ -43,17 +43,31 @@
 
   --margo-color-neutral: #ffffff;
   --margo-color-on-neutral: #000000;
-  --margo-color-main: #f6f6f6;
+  --margo-color-main: #e7e7e7;
   --margo-color-on-main: #151515;
   --margo-color-primary: #57e550;
   --margo-color-primary-darken: #45b93f;
   --margo-color-secondary: #d3d3d3;
-  --margo-color-medium: #7e7e7e;
-  --margo-color-border: #cfcfcf;
+  --margo-color-medium: #858585;
+  --margo-color-border: #cecece;
 
   --margo-shadow-card: 0 8px 6px -4px rgb(220, 220, 220, 0.5);
   --margo-shadow-button: 0px 2px 3px -1px rgb(220, 220, 220, 0.6);
+  --margo-shadow-item: 0px 2px 3px -1px rgb(220, 220, 220, 0.6);
   --margo-shadow-chip: 0 1px 3px -1px rgb(0, 0, 0, 0.6);
+
+  --margo-code-surface: #fbfbfb;
+  --margo-code-bar: #f1f1f1;
+  --margo-code-plain: #24292f;
+  --margo-code-comment: #8b949e;
+  --margo-code-string: #0a7d3f;
+  --margo-code-keyword: #a5309a;
+  --margo-code-number: #b3510f;
+  --margo-code-tag: #1f6fd6;
+  --margo-code-attr: #7a5cd6;
+  --margo-code-fn: #0f7c93;
+  --margo-code-type: #1f6fd6;
+  --margo-code-punct: #6e7781;
 }
 
 .dark {
@@ -71,5 +85,19 @@
 
   --margo-shadow-card: 0 4px 12px -4px rgb(0, 0, 0, 0.5);
   --margo-shadow-button: 0 2px 6px -2px rgb(0, 0, 0, 0.5);
+  --margo-shadow-item: 0 2px 6px -2px rgb(0, 0, 0, 0.5);
   --margo-shadow-chip: 0 1px 3px -1px rgb(0, 0, 0, 0.5);
+
+  --margo-code-surface: #0d0d0d;
+  --margo-code-bar: #161616;
+  --margo-code-plain: #e6e6e6;
+  --margo-code-comment: #6b6b6b;
+  --margo-code-string: #7ee787;
+  --margo-code-keyword: #ff7bd5;
+  --margo-code-number: #ffab70;
+  --margo-code-tag: #79c0ff;
+  --margo-code-attr: #c3a6ff;
+  --margo-code-fn: #56d4dd;
+  --margo-code-type: #79c0ff;
+  --margo-code-punct: #8b949e;
 }

package/src/hoc/background_glow/background_glow.css

@@ -7,26 +7,36 @@
   opacity: 0;
   border-radius: inherit;
   background: radial-gradient(
-    var(--margo-background-glow-size) circle at var(--margo-background-glow-x, 50%) var(--margo-background-glow-y, 50%),
+    var(--margo-background-glow-size, 480px) circle at var(--margo-background-glow-x, 50%) var(--margo-background-glow-y, 50%),
     var(--color-primary),
     transparent 70%
   );
   transition: opacity 300ms ease-out;
 }
 
+.margo-background-glow::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  pointer-events: none;
+  opacity: 0;
+  border-radius: inherit;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='120'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.75' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+  background-size: var(--margo-background-glow-noise-tile, 120px);
+  mix-blend-mode: overlay;
+  transition: opacity 300ms ease-out;
+}
+
 .margo-background-glow:hover::before,
 .margo-background-glow:focus-within::before {
   opacity: var(--margo-background-glow-opacity, 0.1);
 }
 
-.margo-background-glow--size-sm {
-  --margo-background-glow-size: 200px;
+.margo-background-glow:hover::after,
+.margo-background-glow:focus-within::after {
+  opacity: var(--margo-background-glow-noise-opacity, 0.04);
 }
 
-.margo-background-glow--size-md {
-  --margo-background-glow-size: 320px;
-}
 
-.margo-background-glow--size-lg {
-  --margo-background-glow-size: 480px;
-}
+

package/src/hoc/background_glow/background_glow.tsx

@@ -1,17 +1,19 @@
 import { cloneElement } from "react";
 
 import { cn } from "../../utils/cn/cn.js";
-import { backgroundGlowBaseClassName, backgroundGlowSizeClassName } from "./style.js";
+import { backgroundGlowBaseClassName } from "./style.js";
 
-import type { PointerEvent } from "react";
+import type { CSSProperties, PointerEvent } from "react";
 import type { BackgroundGlowProps } from "./type.js";
 
 import "./background_glow.css";
 
-export const BackgroundGlow = ({ children, size = "md" }: BackgroundGlowProps) => {
+export const BackgroundGlow = ({ children, tolerance = 1, opacity = 0.2, noise = 0.04 }: BackgroundGlowProps) => {
   const handlePointerMove = (event: PointerEvent<HTMLElement>) => {
     const bounds = event.currentTarget.getBoundingClientRect();
+    const spread = Math.max(bounds.width, bounds.height) * Math.min(Math.max(tolerance, 0), 1);
 
+    event.currentTarget.style.setProperty("--margo-background-glow-size", `${spread}px`);
     event.currentTarget.style.setProperty("--margo-background-glow-x", `${event.clientX - bounds.left}px`);
     event.currentTarget.style.setProperty("--margo-background-glow-y", `${event.clientY - bounds.top}px`);
 
@@ -19,7 +21,12 @@ export const BackgroundGlow = ({ children, size = "md" }: BackgroundGlowProps) =
   };
 
   return cloneElement(children, {
-    className: cn(backgroundGlowBaseClassName, backgroundGlowSizeClassName[size], children.props.className),
+    className: cn(backgroundGlowBaseClassName, children.props.className),
+    style: {
+      ...children.props.style,
+      "--margo-background-glow-opacity": opacity,
+      "--margo-background-glow-noise-opacity": noise,
+    } as CSSProperties,
     onPointerMove: handlePointerMove,
   });
 };

package/src/hoc/background_glow/style.ts

@@ -1,9 +1 @@
-import type { BackgroundGlowSize } from "./type.js";
-
 export const backgroundGlowBaseClassName = "relative isolate margo-background-glow";
-
-export const backgroundGlowSizeClassName: Record<BackgroundGlowSize, string> = {
-  sm: "margo-background-glow--size-sm",
-  md: "margo-background-glow--size-md",
-  lg: "margo-background-glow--size-lg",
-};

package/src/hoc/background_glow/type.ts

@@ -1,13 +1,14 @@
-import type { PointerEventHandler, ReactElement } from "react";
-
-export type BackgroundGlowSize = "sm" | "md" | "lg";
+import type { CSSProperties, PointerEventHandler, ReactElement } from "react";
 
 export type BackgroundGlowChildProps = {
   className?: string;
+  style?: CSSProperties;
   onPointerMove?: PointerEventHandler<HTMLElement>;
 };
 
 export type BackgroundGlowProps = {
   children: ReactElement<BackgroundGlowChildProps>;
-  size?: BackgroundGlowSize;
+  tolerance?: number;
+  opacity?: number;
+  noise?: number;
 };

package/src/index.ts

@@ -2,8 +2,12 @@ export { Blockquote } from "./components/blockquote/blockquote.js";
 export { Button } from "./components/button/button.js";
 export { Card } from "./components/card/card.js";
 export { Chip } from "./components/chip/chip.js";
+export { Item } from "./components/item/item.js";
+export { NavigationBar } from "./components/navigation_bar/navigation_bar.js";
 export { ProgressBar } from "./components/progress_bar/progress_bar.js";
+export { Table } from "./components/table/table.js";
 export { Splash } from "./components/splash/splash.js";
+export { Snippet } from "./components/snippet/snippet.js";
 export { Spinner } from "./components/spinner/spinner.js";
 export { Tooltip } from "./components/tooltip/tooltip.js";
 
@@ -30,12 +34,23 @@ export type {
 } from "./components/button/type.js";
 export type { CardProps } from "./components/card/type.js";
 export type { ChipProps } from "./components/chip/type.js";
+export type { ItemIconProps, ItemLabelProps, ItemProps } from "./components/item/type.js";
+export type { NavigationBarProps } from "./components/navigation_bar/type.js";
 export type { ProgressBarMode, ProgressBarProps } from "./components/progress_bar/type.js";
+export type {
+  TableBodyProps,
+  TableCellProps,
+  TableHeadCellProps,
+  TableHeadProps,
+  TableProps,
+  TableRowProps,
+} from "./components/table/type.js";
 export type { SplashProps, SplashServeProps } from "./components/splash/type.js";
+export type { SnippetProps, SnippetToken, SnippetTokenType } from "./components/snippet/type.js";
 export type { SpinnerProps } from "./components/spinner/type.js";
 export type { TooltipPosition, TooltipProps } from "./components/tooltip/type.js";
 
-export type { BackgroundGlowProps, BackgroundGlowSize } from "./hoc/background_glow/type.js";
+export type { BackgroundGlowProps } from "./hoc/background_glow/type.js";
 export type { BorderGlowPosition, BorderGlowProps } from "./hoc/border_glow/type.js";
 export type { MaskGradientYProps } from "./hoc/mask_gradient_y/type.js";
 export type { RippleProps } from "./hoc/ripple/type.js";