margo-ui 1.2.1 → 1.2.3

package/margo.css

@@ -3,5 +3,6 @@
 @import "./src/css/theme.css";
 @import "./src/css/custom-variant.css";
 @import "./src/css/utility.css";
+@import "./src/css/grid.css";
 
 @source "../**/*.{ts,tsx,js,mjs}";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "margo-ui",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "A small React UI kit built on Tailwind CSS v4 design tokens, themeable through plain CSS custom properties.",
   "keywords": [
     "react",

package/src/components/progress_bar/progress_bar.css

@@ -18,7 +18,7 @@
 
 .margo-progress-bar[data-mode="indeterminate"]::before {
   inset: 0 auto 0 0;
-  width: 40%;
+  width: 50%;
   animation: margo-progress-bar-indeterminate 800ms ease-in-out infinite;
 }
 

package/src/components/progress_bar/progress_bar.tsx

@@ -10,10 +10,10 @@ import "./progress_bar.css";
 
 export const ProgressBar = <T extends ElementType = "div">({
   animate = true,
-  className,
   mode = "indeterminate",
   style,
   value = 0,
+  className,
   ...rest
 }: ProgressBarProps<T>) => {
   const isDeterminate = mode === "determinate";

package/src/components/splash/splash.css

@@ -0,0 +1,19 @@
+@layer components {
+  [data-margo-splash] {
+    visibility: visible;
+    clip-path: circle(150% at 50% 50%);
+    transition:
+      clip-path 2500ms ease-out,
+      visibility 2500ms ease-out;
+  }
+
+  :root:not(:has([data-margo-splash-serve])) [data-margo-splash] {
+    visibility: hidden;
+    clip-path: circle(0% at 50% 50%);
+  }
+}
+
+:root:has([data-margo-splash-serve][data-margo-splash-instant]) [data-margo-splash] {
+  transition-duration: 0ms;
+  transition-delay: 0ms;
+}

package/src/components/splash/splash.tsx

@@ -0,0 +1,27 @@
+import { Tag } from "react-renderable";
+
+import type { ElementType } from "react";
+import type { SplashProps, SplashServeProps } from "./type.js";
+
+import { cn } from "../../utils/cn/cn.js";
+import "./splash.css";
+
+export const Splash = <T extends ElementType = "div">({ initial = true, className, ...rest }: SplashProps<T>) => (
+  <Tag
+    {...Tag.forward<T>(rest)}
+    inert
+    aria-hidden={true}
+    role="presentation"
+    data-margo-splash=""
+    data-margo-splash-initial={initial}
+    className={cn(
+      "fixed inset-0 z-max",
+      className && "[clip-path:none] margo-splash-idle:[clip-path:none]",
+      className,
+    )}
+  />
+);
+
+Splash.Serve = ({ instant = false }: SplashServeProps) => (
+  <span hidden data-margo-splash-serve="" data-margo-splash-instant={instant || undefined} />
+);

package/src/components/splash/style.ts

@@ -0,0 +1 @@
+export const splashBaseClassName = "margo-splash";

package/src/components/splash/type.ts

@@ -0,0 +1,12 @@
+import type { ElementType } from "react";
+import type { TagProps } from "react-renderable";
+
+export type SplashOwnProps = {
+  initial?: boolean;
+};
+
+export type SplashProps<T extends ElementType = "div"> = TagProps<T, SplashOwnProps>;
+
+export type SplashServeProps = {
+  instant?: boolean;
+};

package/src/css/custom-variant.css

@@ -1 +1,2 @@
 @custom-variant dark (&:where(.dark, .dark *));
+@custom-variant margo-splash-idle (:root:not(:has([data-margo-splash-serve])) &);

package/src/css/grid.css

@@ -0,0 +1,229 @@
+/*
+ * 12-column grid with full-bleed support.
+ *
+ * Tunable from the consumer through four variables only (see variables.css):
+ * --margo-grid-max-width, --margo-grid-padding, --margo-grid-gutter-x,
+ * --margo-grid-gutter-y. Padding and gutters are fully independent: the side
+ * padding is real padding on the container, the gutters are column gaps that
+ * only exist between the 12 columns. Any combination is valid, including a
+ * padding smaller than the gutter.
+ *
+ * Named lines available inside `margo-grid`:
+ * content-start | col-start 1..12 / col-end 1..12 | content-end
+ * Rows have no template and no names: they are addressed by index.
+ *
+ * Full bleed is not a line: it is a negative margin that cancels the distance
+ * between the content area and the viewport edge (--margo-grid-bleed), so it
+ * works from any column and at any nesting depth.
+ */
+
+/*
+ * Root layout container: centers a 12-column content area capped at
+ * --margo-grid-max-width and pads it by --margo-grid-padding on both sides.
+ * Direct children sit on the whole content area by default, so a plain
+ * `<div className="margo-grid"><section /></div>` is already correctly aligned.
+ * That default has zero specificity, so any margo-col-* utility overrides it.
+ *
+ * Use on: page sections, headers, footers — the outermost element of a layout.
+ */
+@utility margo-grid {
+  --margo-grid-bleed: max(var(--margo-grid-padding), calc((100vw - var(--margo-grid-max-width)) / 2));
+
+  width: 100%;
+  max-width: calc(var(--margo-grid-max-width) + var(--margo-grid-padding) * 2);
+  margin-inline: auto;
+  padding-inline: var(--margo-grid-padding);
+
+  display: grid;
+  column-gap: var(--margo-grid-gutter-x);
+  row-gap: var(--margo-grid-gutter-y);
+  grid-template-columns: [content-start] repeat(12, [col-start] minmax(0, 1fr) [col-end]) [content-end];
+
+  :where(&) > * {
+    grid-column-start: content-start;
+    grid-column-end: content-end;
+  }
+}
+
+/*
+ * Nested grid that reuses the parent tracks and line names instead of creating
+ * new ones, so children keep aligning to the same 12 columns at any depth.
+ * Must be a child of margo-grid (or of another margo-grid-sub) and must span
+ * the columns it wants to inherit — as a child of margo-grid it already covers
+ * the whole content area.
+ *
+ * Children are auto-placed: one column each unless they carry a margo-col-*
+ * utility, so `margo-col-span-6` items flow two per row.
+ *
+ * Use on: a list/card wrapper whose grandchildren still need global alignment.
+ */
+@utility margo-grid-sub {
+  display: grid;
+  grid-template-columns: subgrid;
+  row-gap: var(--margo-grid-gutter-y);
+}
+
+/*
+ * Standalone 12-column grid: same line names and gutters, but no max-width and
+ * no side padding — it fills whatever box it is placed in.
+ *
+ * Use on: an isolated component that needs 12 columns of its own, outside of
+ * (or independent from) the page layout.
+ */
+@utility margo-grid-flat {
+  display: grid;
+  grid-template-columns: [content-start] repeat(12, [col-start] minmax(0, 1fr) [col-end]) [content-end];
+  column-gap: var(--margo-grid-gutter-x);
+  row-gap: var(--margo-grid-gutter-y);
+}
+
+/*
+ * Full bleed: edge to edge of the viewport, escaping both the max-width and the
+ * side padding. Use on: background bands, hero images, sticky bars.
+ * To keep inner content on the grid, nest a margo-grid inside it.
+ */
+@utility margo-col-full {
+  grid-column-start: content-start;
+  grid-column-end: content-end;
+  margin-inline: calc(var(--margo-grid-bleed) * -1);
+}
+
+/*
+ * 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.
+ */
+@utility margo-col-content {
+  grid-column-start: content-start;
+  grid-column-end: content-end;
+  margin-inline: 0;
+}
+
+/*
+ * A single column, by index: `margo-col-4` occupies column 4 only.
+ * Use for one-cell items; combine with variants, e.g. `900:margo-col-7`.
+ */
+@utility margo-col-* {
+  grid-column-start: col-start --value(integer);
+  grid-column-end: col-end --value(integer);
+}
+
+/* Bleed off the left edge of the viewport, keeping the current end line. */
+@utility margo-col-start-full {
+  grid-column-start: content-start;
+  margin-inline-start: calc(var(--margo-grid-bleed) * -1);
+}
+
+/* Start at the left edge of the content area, dropping any left bleed. */
+@utility margo-col-start-content {
+  grid-column-start: content-start;
+  margin-inline-start: 0;
+}
+
+/*
+ * Start at the beginning of column N: `margo-col-start-5`.
+ * Pairs with margo-col-end-* (explicit range) or margo-col-span-* (length).
+ */
+@utility margo-col-start-* {
+  grid-column-start: col-start --value(integer);
+}
+
+/* Bleed off the right edge of the viewport, keeping the current start line. */
+@utility margo-col-end-full {
+  grid-column-end: content-end;
+  margin-inline-end: calc(var(--margo-grid-bleed) * -1);
+}
+
+/* End at the right edge of the content area, dropping any right bleed. */
+@utility margo-col-end-content {
+  grid-column-end: content-end;
+  margin-inline-end: 0;
+}
+
+/*
+ * End at the end of column N, inclusive: `margo-col-start-5 margo-col-end-8`
+ * covers columns 5 through 8.
+ */
+@utility margo-col-end-* {
+  grid-column-end: col-end --value(integer);
+}
+
+/* Span the full bleed width regardless of where the item starts. */
+@utility margo-col-span-full {
+  grid-column-start: content-start;
+  grid-column-end: content-end;
+  margin-inline: calc(var(--margo-grid-bleed) * -1);
+}
+
+/*
+ * Span N columns from wherever the item starts: `margo-col-span-6`.
+ * In margo-grid-sub / margo-grid-flat the item keeps auto-placing, so
+ * `margo-col-span-12 900:margo-col-span-6` items flow one per row on mobile
+ * and two per row from 900 up. As a direct child of margo-grid the start is
+ * pinned to the content edge instead.
+ */
+@utility margo-col-span-* {
+  grid-column-end: span --value(integer);
+}
+
+/*
+ * Rows are implicit and unnamed, so they are addressed by index only.
+ * `margo-row-2` puts the item on the second row, which is how two items are
+ * made to share a row band or to overlap a column that spans several rows.
+ */
+@utility margo-row-* {
+  grid-row-start: --value(integer);
+  grid-row-end: span 1;
+}
+
+/*
+ * Start on row N and keep the current end: `margo-row-start-2`.
+ * Pair with margo-row-span-* for the length; there is no margo-row-end-*,
+ * because without named row lines an end index would mean the line before
+ * the row, the opposite of how margo-col-end-* reads.
+ */
+@utility margo-row-start-* {
+  grid-row-start: --value(integer);
+}
+
+/* Span N rows from wherever the item starts: `margo-row-span-2`. */
+@utility margo-row-span-* {
+  grid-row-end: span --value(integer);
+}
+
+/*
+ * Gutter overrides, on the spacing scale: `margo-gutter-y-0`, `margo-gutter-x-4`.
+ * They set the grid variables rather than the gap properties, so they never
+ * depend on utility order to win, and they cascade into nested margo-grid /
+ * margo-grid-sub unless those override the gutter again.
+ */
+@utility margo-gutter-* {
+  --margo-grid-gutter-x: --spacing(--value(integer));
+  --margo-grid-gutter-y: --spacing(--value(integer));
+}
+
+@utility margo-gutter-x-* {
+  --margo-grid-gutter-x: --spacing(--value(integer));
+}
+
+@utility margo-gutter-y-* {
+  --margo-grid-gutter-y: --spacing(--value(integer));
+}
+
+/*
+ * Side padding override, on the spacing scale: `margo-padding-8`.
+ * Also feeds --margo-grid-bleed, so full-bleed children stay exact.
+ */
+@utility margo-padding-* {
+  --margo-grid-padding: --spacing(--value(integer));
+}
+
+/*
+ * Non-grid escape hatch: same max-width and side padding as margo-grid, but a
+ * plain block. Use when a section needs the layout width without any columns.
+ */
+@utility margo-container {
+  width: 100%;
+  max-width: calc(var(--margo-grid-max-width) + var(--margo-grid-padding) * 2);
+  margin-inline: auto;
+  padding-inline: var(--margo-grid-padding);
+}

package/src/css/variables.css

@@ -30,6 +30,12 @@
   --margo-font-weight-black: 900;
 
   --margo-border-width-2: 1.5px;
+
+  --margo-grid-max-width: 80rem;
+  --margo-grid-padding: 1rem;
+  --margo-grid-gutter-x: 2rem;
+  --margo-grid-gutter-y: 2rem;
+  --margo-grid-bleed: max(var(--margo-grid-padding), calc((100vw - var(--margo-grid-max-width)) / 2));
 }
 
 :root {

package/src/hoc/border_glow/border_glow.css

@@ -5,7 +5,7 @@
   pointer-events: none;
   opacity: 0;
   background: radial-gradient(
-    480px circle at var(--margo-border-glow-x, 70%) var(--margo-border-glow-y, 70%),
+    var(--margo-border-glow-size, 480px) circle at var(--margo-border-glow-x, 70%) var(--margo-border-glow-y, 70%),
     var(--color-primary-darken),
     transparent 70%
   );

package/src/hoc/border_glow/border_glow.tsx

@@ -8,12 +8,14 @@ import type { BorderGlowProps } from "./type.js";
 
 import "./border_glow.css";
 
-export const BorderGlow = ({ children, position = "all" }: BorderGlowProps) => {
+export const BorderGlow = ({ children, position = "all", tolerance = 1 }: BorderGlowProps) => {
   const handlePointerMove = (event: PointerEvent<HTMLElement>) => {
     const bounds = event.currentTarget.getBoundingClientRect();
     const x = event.clientX - bounds.left;
     const y = event.clientY - bounds.top;
+    const size = Math.max(bounds.width, bounds.height) * Math.min(Math.max(tolerance, 0), 1);
 
+    event.currentTarget.style.setProperty("--margo-border-glow-size", `${size}px`);
     event.currentTarget.style.setProperty("--margo-border-glow-x", `${position === "right" ? bounds.width - x : x}px`);
     event.currentTarget.style.setProperty("--margo-border-glow-y", `${position === "down" ? bounds.height - y : y}px`);
 

package/src/hoc/border_glow/type.ts

@@ -10,4 +10,5 @@ export type BorderGlowChildProps = {
 export type BorderGlowProps = {
   children: ReactElement<BorderGlowChildProps>;
   position?: BorderGlowPosition;
+  tolerance?: number;
 };

package/src/hoc/mask_gradient_y/mask_gradient_y.css

@@ -0,0 +1,17 @@
+.margo-mask-gradient-y {
+  --margo-mask-gradient-y-offset-top: 0px;
+  --margo-mask-gradient-y-offset-bottom: 0px;
+  --margo-mask-gradient-y-fade-top: 2rem;
+  --margo-mask-gradient-y-fade-bottom: 2rem;
+
+  --margo-mask-gradient-y-image: linear-gradient(
+    to bottom,
+    transparent var(--margo-mask-gradient-y-offset-top),
+    #000 calc(var(--margo-mask-gradient-y-offset-top) + var(--margo-mask-gradient-y-fade-top)),
+    #000 calc(100% - var(--margo-mask-gradient-y-offset-bottom) - var(--margo-mask-gradient-y-fade-bottom)),
+    transparent calc(100% - var(--margo-mask-gradient-y-offset-bottom))
+  );
+
+  -webkit-mask-image: var(--margo-mask-gradient-y-image);
+  mask-image: var(--margo-mask-gradient-y-image);
+}

package/src/hoc/mask_gradient_y/mask_gradient_y.tsx

@@ -0,0 +1,22 @@
+import { cloneElement } from "react";
+
+import { cn } from "../../utils/cn/cn.js";
+
+import type { CSSProperties } from "react";
+import type { MaskGradientYProps } from "./type.js";
+
+import "./mask_gradient_y.css";
+
+export const MaskGradientY = ({ children, fade, fadeTop, fadeBottom, offsetTop, offsetBottom }: MaskGradientYProps) => {
+  const style = {
+    "--margo-mask-gradient-y-offset-top": offsetTop,
+    "--margo-mask-gradient-y-offset-bottom": offsetBottom,
+    "--margo-mask-gradient-y-fade-top": fadeTop ?? fade,
+    "--margo-mask-gradient-y-fade-bottom": fadeBottom ?? fade,
+  } as CSSProperties;
+
+  return cloneElement(children, {
+    className: cn("margo-mask-gradient-y", children.props.className),
+    style: { ...style, ...children.props.style },
+  });
+};

package/src/hoc/mask_gradient_y/type.ts

@@ -0,0 +1,15 @@
+import type { CSSProperties, ReactElement } from "react";
+
+export type MaskGradientYChildProps = {
+  className?: string;
+  style?: CSSProperties;
+};
+
+export type MaskGradientYProps = {
+  children: ReactElement<MaskGradientYChildProps>;
+  fade?: string;
+  fadeTop?: string;
+  fadeBottom?: string;
+  offsetTop?: string;
+  offsetBottom?: string;
+};

package/src/index.ts

@@ -3,11 +3,13 @@ export { Button } from "./components/button/button.js";
 export { Card } from "./components/card/card.js";
 export { Chip } from "./components/chip/chip.js";
 export { ProgressBar } from "./components/progress_bar/progress_bar.js";
+export { Splash } from "./components/splash/splash.js";
 export { Spinner } from "./components/spinner/spinner.js";
 export { Tooltip } from "./components/tooltip/tooltip.js";
 
 export { BackgroundGlow } from "./hoc/background_glow/background_glow.js";
 export { BorderGlow } from "./hoc/border_glow/border_glow.js";
+export { MaskGradientY } from "./hoc/mask_gradient_y/mask_gradient_y.js";
 export { Ripple } from "./hoc/ripple/ripple.js";
 
 export { MetaColorScheme } from "./meta/meta_color_scheme/meta_color_scheme.js";
@@ -29,11 +31,13 @@ export type {
 export type { CardProps } from "./components/card/type.js";
 export type { ChipProps } from "./components/chip/type.js";
 export type { ProgressBarMode, ProgressBarProps } from "./components/progress_bar/type.js";
+export type { SplashProps, SplashServeProps } from "./components/splash/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 { 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";
 
 export type { MargoTheme, MargoThemeClient } from "./utils/theme/type.js";

package/src/utils/cn/cn.ts

@@ -3,10 +3,45 @@ import { extendTailwindMerge } from "tailwind-merge";
 
 import type { ClassValue } from "clsx";
 
-const twMerge = extendTailwindMerge({
+const isNumber = (value: string) => /^\d+$/.test(value);
+
+const isColumnLine = (value: string) => value === "full" || value === "content" || isNumber(value);
+
+type MargoClassGroupIds =
+  | "margo-col"
+  | "margo-col-start"
+  | "margo-col-end"
+  | "margo-col-span"
+  | "margo-row"
+  | "margo-row-start"
+  | "margo-row-span"
+  | "margo-gutter"
+  | "margo-gutter-x"
+  | "margo-gutter-y"
+  | "margo-padding";
+
+const twMerge = extendTailwindMerge<MargoClassGroupIds>({
   extend: {
     classGroups: {
       "font-size": ["text-mc"],
+      "margo-col": [{ "margo-col": [isColumnLine] }],
+      "margo-col-start": [{ "margo-col-start": [isColumnLine] }],
+      "margo-col-end": [{ "margo-col-end": [isColumnLine] }],
+      "margo-col-span": [{ "margo-col-span": [isColumnLine] }],
+      "margo-row": [{ "margo-row": [isNumber] }],
+      "margo-row-start": [{ "margo-row-start": [isNumber] }],
+      "margo-row-span": [{ "margo-row-span": [isNumber] }],
+      "margo-gutter": [{ "margo-gutter": [isNumber] }],
+      "margo-gutter-x": [{ "margo-gutter-x": [isNumber] }],
+      "margo-gutter-y": [{ "margo-gutter-y": [isNumber] }],
+      "margo-padding": [{ "margo-padding": [isNumber] }],
+    },
+    conflictingClassGroups: {
+      "margo-col": ["margo-col-start", "margo-col-end", "margo-col-span"],
+      "margo-col-span": ["margo-col-end"],
+      "margo-col-end": ["margo-col-span"],
+      "margo-row": ["margo-row-start", "margo-row-span"],
+      "margo-gutter": ["margo-gutter-x", "margo-gutter-y"],
     },
   },
 });