release: ship useGlassHighlightEffect in @protohiro/effects@0.3.0

snwolak · snwolak · commit cd579ef7612f · 2026-03-06T15:19:05.000+01:00
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Protohiro Effects
 
-Protohiro Effects is a zero-wrapper React library for hard CSS effects like gradient borders, glow rings, noise overlays, and spotlight overlays.
+Protohiro Effects is a zero-wrapper React library for hard CSS effects like gradient borders, glass highlights, glow rings, noise overlays, and spotlight overlays.
 
 ## Live demo
 
@@ -40,6 +40,20 @@ Options:
 - `angle?: string | number`
 - `disabled?: boolean`
 
+### `useGlassHighlightEffect(options)`
+
+Options:
+- `color?: string`
+- `edgeOpacity?: number`
+- `sheenOpacity?: number`
+- `tintOpacity?: number`
+- `angle?: string | number`
+- `blur?: string | number`
+- `radius?: string | number`
+- `inset?: string | number`
+- `saturate?: number`
+- `disabled?: boolean`
+
 ### `useGlowEffect(options)`
 
 Options:
diff --git a/apps/demo/CHANGELOG.md b/apps/demo/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @protohiro/effects-demo
 
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @protohiro/effects@0.3.0
+
 ## 0.1.2
 
 ### Patch Changes
diff --git a/apps/demo/package.json b/apps/demo/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@protohiro/effects-demo",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/apps/demo/src/App.tsx b/apps/demo/src/App.tsx
@@ -1,4 +1,5 @@
 import {
+  useGlassHighlightEffect,
   useGlowEffect,
   useGradientBorderEffect,
   useNoiseEffect,
@@ -45,6 +46,10 @@ function useGlowStoryHook(options: DemoOptions): RefCallback<HTMLElement> {
   return useGlowEffect(options);
 }
 
+function useGlassHighlightStoryHook(options: DemoOptions): RefCallback<HTMLElement> {
+  return useGlassHighlightEffect(options);
+}
+
 function useNoiseStoryHook(options: DemoOptions): RefCallback<HTMLElement> {
   return useNoiseEffect(options);
 }
@@ -104,6 +109,45 @@ const STORIES: EffectStory[] = [
       { key: 'disabled', label: 'Disabled', type: 'checkbox' },
     ],
   },
+  {
+    id: 'glass-highlight',
+    title: 'Glass Highlight',
+    description: 'Glassy edge light and sheen overlay for premium surfaces.',
+    hookName: 'useGlassHighlightEffect',
+    componentName: 'GlassHighlightCard',
+    previewText: 'Glass Highlight Surface',
+    previewElement: 'article',
+    previewStyle: {
+      background:
+        'linear-gradient(145deg, rgba(15, 23, 42, 0.96) 0%, rgba(30, 41, 59, 0.92) 52%, rgba(15, 23, 42, 0.98) 100%)',
+      color: '#e2e8f0',
+      border: '1px solid rgba(148, 163, 184, 0.22)',
+      boxShadow:
+        '0 18px 48px rgba(15, 23, 42, 0.34), inset 0 1px 0 rgba(255, 255, 255, 0.04)',
+    } as CSSProperties,
+    hook: useGlassHighlightStoryHook,
+    defaults: {
+      color: '#a855f7',
+      edgeOpacity: 0.3,
+      sheenOpacity: 0.44,
+      tintOpacity: 0.56,
+      angle: '132deg',
+      blur: 0,
+      inset: 0,
+      saturate: 1.85,
+    },
+    controls: [
+      { key: 'color', label: 'Color', type: 'color' },
+      { key: 'edgeOpacity', label: 'Edge opacity', type: 'range', min: 0, max: 1, step: 0.01 },
+      { key: 'sheenOpacity', label: 'Sheen opacity', type: 'range', min: 0, max: 1, step: 0.01 },
+      { key: 'tintOpacity', label: 'Tint opacity', type: 'range', min: 0, max: 1, step: 0.01 },
+      { key: 'angle', label: 'Angle', type: 'text' },
+      { key: 'blur', label: 'Blur', type: 'number', min: 0, max: 40, step: 1 },
+      { key: 'inset', label: 'Inset', type: 'number', min: -8, max: 24, step: 1 },
+      { key: 'saturate', label: 'Saturate', type: 'range', min: 0, max: 2, step: 0.01 },
+      { key: 'disabled', label: 'Disabled', type: 'checkbox' },
+    ],
+  },
   {
     id: 'noise',
     title: 'Noise',
@@ -299,7 +343,7 @@ function EffectPlayground({ story }: { story: EffectStory }) {
         </header>
         <div className="demo-preview">
           <PreviewTag ref={ref} className={previewClassName} style={story.previewStyle}>
-            {story.previewText}
+            <span className="demo-card-content">{story.previewText}</span>
           </PreviewTag>
         </div>
       </div>
diff --git a/apps/demo/src/styles.css b/apps/demo/src/styles.css
@@ -147,6 +147,13 @@ h1 {
   font-weight: 600;
 }
 
+.demo-card-content {
+  position: relative;
+  z-index: 1;
+  display: inline-block;
+  text-shadow: 0 2px 12px rgba(2, 6, 23, 0.42);
+}
+
 .demo-card-spotlight {
   min-height: 136px;
   display: flex;
diff --git a/package.json b/package.json
@@ -50,7 +50,7 @@
     {
       "name": "@protohiro/effects",
       "path": "packages/react/dist/index.js",
-      "limit": "5.5 kB"
+      "limit": "5.6 kB"
     }
   ]
 }
diff --git a/packages/react/CHANGELOG.md b/packages/react/CHANGELOG.md
@@ -1,5 +1,16 @@
 # @protohiro/effects
 
+## 0.3.0
+
+### Minor Changes
+
+- Add a new `useGlassHighlightEffect` hook for premium glass-sheen surfaces.
+
+  Highlights:
+  - Adds a new glass highlight effect with configurable edge, sheen, tint, blur, inset, and saturation options.
+  - Extends the shared effect stylesheet and demo coverage for the new effect.
+  - Updates public docs and exports for the expanded hook surface.
+
 ## 0.2.0
 
 ### Minor Changes
diff --git a/packages/react/README.md b/packages/react/README.md
@@ -22,10 +22,25 @@ export function Button() {
 ## Hooks
 
 - `useGradientBorderEffect`
+- `useGlassHighlightEffect`
 - `useGlowEffect`
 - `useNoiseEffect`
 - `useSpotlightEffect`
 
+### `useGlassHighlightEffect(options)`
+
+Options:
+- `color?: string`
+- `edgeOpacity?: number`
+- `sheenOpacity?: number`
+- `tintOpacity?: number`
+- `angle?: string | number`
+- `blur?: string | number`
+- `radius?: string | number`
+- `inset?: string | number`
+- `saturate?: number`
+- `disabled?: boolean`
+
 Live demo:
 https://libs.protohiro.com/effects/
 
diff --git a/packages/react/package.json b/packages/react/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@protohiro/effects",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Zero-wrapper React hooks for composable CSS effects.",
   "license": "MIT",
   "type": "module",
diff --git a/packages/react/src/effects/useGlassHighlightEffect.ts b/packages/react/src/effects/useGlassHighlightEffect.ts
@@ -0,0 +1,62 @@
+import { toCssAngle, toCssLength, toCssNumber } from '@protohiro/effects-core';
+import { useMemo } from 'react';
+
+import type { GlassHighlightOptions } from '../types';
+import { EFFECT_STYLES } from '../shared/effectStyles';
+import { useCssEffect } from '../shared/useCssEffect';
+
+const STYLE_ID = 'protohiro-effects-base';
+
+function clampUnit(value: number | undefined): number | undefined {
+  if (value === undefined || Number.isNaN(value)) {
+    return undefined;
+  }
+
+  return Math.max(0, Math.min(1, value));
+}
+
+export function useGlassHighlightEffect<T extends HTMLElement = HTMLElement>(
+  options: GlassHighlightOptions = {},
+) {
+  const edgeOpacity = clampUnit(options.edgeOpacity);
+  const sheenOpacity = clampUnit(options.sheenOpacity);
+  const tintOpacity = clampUnit(options.tintOpacity);
+  const saturate =
+    options.saturate === undefined || Number.isNaN(options.saturate)
+      ? undefined
+      : Math.max(0, options.saturate);
+
+  const vars = useMemo(
+    () => ({
+      '--pe-gh-color': options.color,
+      '--pe-gh-edge-opacity': toCssNumber(edgeOpacity),
+      '--pe-gh-sheen-opacity': toCssNumber(sheenOpacity),
+      '--pe-gh-tint-opacity': toCssNumber(tintOpacity),
+      '--pe-gh-angle': toCssAngle(options.angle),
+      '--pe-gh-blur': toCssLength(options.blur),
+      '--pe-gh-radius': toCssLength(options.radius),
+      '--pe-gh-inset': toCssLength(options.inset),
+      '--pe-gh-saturate': toCssNumber(saturate),
+    }),
+    [
+      options.color,
+      edgeOpacity,
+      sheenOpacity,
+      tintOpacity,
+      options.angle,
+      options.blur,
+      options.radius,
+      options.inset,
+      saturate,
+    ],
+  );
+
+  return useCssEffect<T>({
+    className: 'pe-glass-highlight',
+    userClassName: options.className,
+    vars,
+    disabled: options.disabled,
+    styleId: STYLE_ID,
+    styleText: EFFECT_STYLES,
+  });
+}
diff --git a/packages/react/src/index.test.tsx b/packages/react/src/index.test.tsx
@@ -3,7 +3,13 @@ import React, { StrictMode, act, useState } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { renderToString } from 'react-dom/server';
 
-import { useGlowEffect, useGradientBorderEffect, useNoiseEffect, useSpotlightEffect } from './index';
+import {
+  useGlassHighlightEffect,
+  useGlowEffect,
+  useGradientBorderEffect,
+  useNoiseEffect,
+  useSpotlightEffect,
+} from './index';
 
 function GradientProbe(props: { thickness?: number }) {
   const ref = useGradientBorderEffect({ thickness: props.thickness ?? 3, colors: '#f00, #00f' });
@@ -15,6 +21,15 @@ function NoiseProbe() {
   return <div ref={ref}>Noise</div>;
 }
 
+function GlassProbe(props: { sheenOpacity?: number; blur?: number; color?: string }) {
+  const ref = useGlassHighlightEffect({
+    sheenOpacity: props.sheenOpacity ?? 0.24,
+    blur: props.blur ?? 12,
+    color: props.color ?? '#7dd3fc',
+  });
+  return <div ref={ref}>Glass</div>;
+}
+
 function SpotlightProbe(props: {
   followPointer?: boolean;
   x?: number;
@@ -87,6 +102,46 @@ describe('react effect hooks', () => {
     expect(div?.style.getPropertyValue('--pe-glow-opacity')).toBe('0.8');
   });
 
+  it('attaches and detaches glass highlight class and vars', () => {
+    const { container, unmount } = render(<GlassProbe sheenOpacity={0.34} blur={16} color="#c084fc" />);
+    const div = container.querySelector('div');
+
+    expect(div).not.toBeNull();
+    expect(div?.classList.contains('pe-glass-highlight')).toBe(true);
+    expect(div?.style.getPropertyValue('--pe-gh-sheen-opacity')).toBe('0.34');
+    expect(div?.style.getPropertyValue('--pe-gh-blur')).toBe('16px');
+    expect(div?.style.getPropertyValue('--pe-gh-color')).toBe('#c084fc');
+
+    unmount();
+
+    expect(div?.classList.contains('pe-glass-highlight')).toBe(false);
+    expect(div?.style.getPropertyValue('--pe-gh-sheen-opacity')).toBe('');
+    expect(div?.style.getPropertyValue('--pe-gh-blur')).toBe('');
+    expect(div?.style.getPropertyValue('--pe-gh-color')).toBe('');
+  });
+
+  it('updates glass highlight vars on options change', () => {
+    function Probe() {
+      const [edgeOpacity, setEdgeOpacity] = useState(0.16);
+      const ref = useGlassHighlightEffect({ edgeOpacity, angle: 24 });
+
+      return (
+        <>
+          <div ref={ref}>Glass</div>
+          <button onClick={() => setEdgeOpacity(0.44)}>Update</button>
+        </>
+      );
+    }
+
+    const { container, getByRole } = render(<Probe />);
+    const div = container.querySelector('div');
+
+    expect(div?.style.getPropertyValue('--pe-gh-edge-opacity')).toBe('0.16');
+    expect(div?.style.getPropertyValue('--pe-gh-angle')).toBe('24deg');
+    fireEvent.click(getByRole('button'));
+    expect(div?.style.getPropertyValue('--pe-gh-edge-opacity')).toBe('0.44');
+  });
+
   it('works without strict mode console errors', () => {
     const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
 
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
@@ -1,10 +1,12 @@
+export { useGlassHighlightEffect } from './effects/useGlassHighlightEffect';
 export { useGradientBorderEffect } from './effects/useGradientBorderEffect';
 export { useGlowEffect } from './effects/useGlowEffect';
 export { useNoiseEffect } from './effects/useNoiseEffect';
 export { useSpotlightEffect } from './effects/useSpotlightEffect';
 
 export type {
   EffectBaseOptions,
+  GlassHighlightOptions,
   GlowOptions,
   GradientBorderOptions,
   NoiseOptions,
diff --git a/packages/react/src/shared/effectStyles.ts b/packages/react/src/shared/effectStyles.ts
diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@protohiro/effects-demo",`
`3`		`- "version": "0.1.2",`
	`3`	`+ "version": "0.1.3",`
`4`	`4`	`"private": true,`
`5`	`5`	`"type": "module",`
`6`	`6`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -50,7 +50,7 @@`
`50`	`50`	`{`
`51`	`51`	`"name": "@protohiro/effects",`
`52`	`52`	`"path": "packages/react/dist/index.js",`
`53`		`- "limit": "5.5 kB"`
	`53`	`+ "limit": "5.6 kB"`
`54`	`54`	`}`
`55`	`55`	`]`
`56`	`56`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@protohiro/effects",`
`3`		`- "version": "0.2.0",`
	`3`	`+ "version": "0.3.0",`
`4`	`4`	`"description": "Zero-wrapper React hooks for composable CSS effects.",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"type": "module",`