@zakisheriff/liquid-glass 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,379 @@
1
+ # <div align="center">@zakisheriff/liquid-glass</div>
2
+
3
+ <div align="center">
4
+ <strong>Apple-Inspired iOS 26 Liquid Glass UI Components for React</strong>
5
+ </div>
6
+
7
+ <br />
8
+
9
+ <div align="center">
10
+
11
+ ![React](https://img.shields.io/badge/React-%3E%3D17-61dafb?style=for-the-badge&logo=react&logoColor=white)
12
+ ![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
13
+ ![CSS](https://img.shields.io/badge/CSS-Backdrop%20Filter-1572B6?style=for-the-badge&logo=css3&logoColor=white)
14
+ ![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
15
+
16
+ <br />
17
+
18
+ <a href="https://www.npmjs.com/package/@zakisheriff/liquid-glass">
19
+ <img src="https://img.shields.io/badge/View%20on%20npm-Install%20Package-CB3837?style=for-the-badge&logo=npm&logoColor=white" height="50" />
20
+ </a>
21
+
22
+ <br />
23
+ <br />
24
+
25
+ **[View on GitHub: https://github.com/zakisheriff/Liquid-Glass](https://github.com/zakisheriff/Liquid-Glass)**
26
+
27
+ </div>
28
+
29
+ <br />
30
+
31
+ > **"Glass should feel physical, not painted on."**
32
+ >
33
+ > `@zakisheriff/liquid-glass` brings Apple's liquid glass aesthetic to React.
34
+ > Built with layered shadows, prismatic borders, animated shine overlays, and native CSS blur, it turns ordinary interface elements into tactile glass surfaces.
35
+
36
+ ---
37
+
38
+ ## ๐ŸŒŸ Vision
39
+
40
+ Liquid Glass exists to be:
41
+
42
+ - **A polished React component library** for building premium glass interfaces quickly
43
+ - **A native CSS-first design system** with no heavy visual runtime
44
+ - **A reusable foundation** for buttons, cards, inputs, sheets, navigation, and custom glass components
45
+
46
+ ---
47
+
48
+ ## โœจ Why Liquid Glass?
49
+
50
+ Most glassmorphism is just a translucent rectangle with blur.
51
+ Liquid Glass goes deeper with **physical depth, refracted edges, animated highlights, and tactile interaction states**.
52
+
53
+ It is designed for teams who want Apple-inspired surfaces without rebuilding the same effect from scratch in every project.
54
+
55
+ ---
56
+
57
+ ## ๐ŸŽจ Apple-Inspired Liquid Glass Design
58
+
59
+ - **Layered Surface Depth**
60
+ Multiple inset and outer shadows create the feeling of glass floating above the interface.
61
+
62
+ - **Prismatic Edge Refraction**
63
+ Conic-gradient borders with mask compositing simulate light catching the rim of glass.
64
+
65
+ - **Animated Shine**
66
+ Subtle hover glints and shimmer states make interactive elements feel alive.
67
+
68
+ - **Native Backdrop Blur**
69
+ CSS `backdrop-filter: blur()` creates real frosted-glass depth over page content.
70
+
71
+ - **System-Friendly Styling**
72
+ Components inherit typography and layout naturally, so they fit inside existing React apps.
73
+
74
+ ---
75
+
76
+ ## ๐Ÿงฉ Component Library
77
+
78
+ - **GlassButton**
79
+ Pill-shaped action button with depth, shimmer, variants, sizes, and press feedback.
80
+
81
+ - **GlassCard**
82
+ Flexible glass container for panels, sections, previews, and grouped content.
83
+
84
+ - **GlassInput**
85
+ Glass-surfaced text input with focus animation and optional floating label.
86
+
87
+ - **GlassSheet**
88
+ Bottom sheet/modal overlay with smooth slide-up animation and glass backdrop.
89
+
90
+ - **GlassNav**
91
+ Pill navigation with glass surface and sliding active indicator.
92
+
93
+ - **LiquidGlassFilter**
94
+ Advanced SVG filter provider for custom glass experiments.
95
+
96
+ ---
97
+
98
+ ## ๐Ÿช„ Hooks for Custom Glass
99
+
100
+ - **useGlassEffect**
101
+ Generates glass styles and filter IDs for building custom glass components.
102
+
103
+ - **useGlassAnimation**
104
+ Tracks hover, press, and focus states for interactive glass behavior.
105
+
106
+ ---
107
+
108
+ ## ๐Ÿ“ Project Structure
109
+
110
+ ```text
111
+ liquid-glass/
112
+ โ”œโ”€โ”€ src/
113
+ โ”‚ โ”œโ”€โ”€ index.ts # Public package exports
114
+ โ”‚ โ”œโ”€โ”€ components/
115
+ โ”‚ โ”‚ โ”œโ”€โ”€ GlassButton/
116
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ GlassButton.tsx # Liquid glass button component
117
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ GlassButton.css # Button-specific styles
118
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ index.ts # Component barrel export
119
+ โ”‚ โ”‚ โ”œโ”€โ”€ GlassCard/
120
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ GlassCard.tsx # Glass container component
121
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ index.ts
122
+ โ”‚ โ”‚ โ”œโ”€โ”€ GlassInput/
123
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ GlassInput.tsx # Glass text input
124
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ index.ts
125
+ โ”‚ โ”‚ โ”œโ”€โ”€ GlassSheet/
126
+ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ GlassSheet.tsx # Bottom sheet/modal surface
127
+ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ index.ts
128
+ โ”‚ โ”‚ โ””โ”€โ”€ GlassNav/
129
+ โ”‚ โ”‚ โ”œโ”€โ”€ GlassNav.tsx # Glass navigation component
130
+ โ”‚ โ”‚ โ””โ”€โ”€ index.ts
131
+ โ”‚ โ”œโ”€โ”€ hooks/
132
+ โ”‚ โ”‚ โ”œโ”€โ”€ useGlassAnimation.ts # Interaction state hook
133
+ โ”‚ โ”‚ โ””โ”€โ”€ useGlassEffect.ts # Custom glass style hook
134
+ โ”‚ โ”œโ”€โ”€ filters/
135
+ โ”‚ โ”‚ โ””โ”€โ”€ LiquidGlassFilter.tsx # Advanced SVG filter provider
136
+ โ”‚ โ””โ”€โ”€ styles/
137
+ โ”‚ โ””โ”€โ”€ base.css # Core liquid glass styles
138
+ โ”œโ”€โ”€ package.json # Package metadata and scripts
139
+ โ”œโ”€โ”€ tsconfig.json # TypeScript configuration
140
+ โ””โ”€โ”€ tsup.config.ts # Build configuration
141
+ ```
142
+
143
+ ---
144
+
145
+ ## ๐Ÿš€ Quick Start
146
+
147
+ ### Prerequisites
148
+
149
+ - **Node.js** (v18+ recommended)
150
+ - **React** (v17+)
151
+ - **React DOM** (v17+)
152
+
153
+ ### 1. Install the Package
154
+
155
+ ```bash
156
+ npm install @zakisheriff/liquid-glass
157
+ ```
158
+
159
+ ```bash
160
+ yarn add @zakisheriff/liquid-glass
161
+ ```
162
+
163
+ ```bash
164
+ pnpm add @zakisheriff/liquid-glass
165
+ ```
166
+
167
+ ### 2. Import Styles
168
+
169
+ ```tsx
170
+ import '@zakisheriff/liquid-glass/styles.css';
171
+ ```
172
+
173
+ ### 3. Use Components
174
+
175
+ ```tsx
176
+ import { GlassButton, GlassCard } from '@zakisheriff/liquid-glass';
177
+ import '@zakisheriff/liquid-glass/styles.css';
178
+
179
+ function App() {
180
+ return (
181
+ <main style={{ minHeight: '100vh', padding: 40, background: '#f3f4f6' }}>
182
+ <GlassCard padding="32px" radius="24px" shimmer>
183
+ <h2>Hello, Glass</h2>
184
+ <p>Build tactile glass interfaces with React.</p>
185
+
186
+ <GlassButton size="lg" shimmer onClick={() => alert('Clicked!')}>
187
+ Get Started
188
+ </GlassButton>
189
+ </GlassCard>
190
+ </main>
191
+ );
192
+ }
193
+ ```
194
+
195
+ ---
196
+
197
+ ## ๐ŸŽฏ Key Features
198
+
199
+ โœ… **React Components** โ€” Buttons, cards, inputs, sheets, and navigation
200
+ โœ… **TypeScript Support** โ€” Fully typed exports for component props and hooks
201
+ โœ… **CSS-First Effects** โ€” Uses native CSS blur, shadows, masks, and gradients
202
+ โœ… **Interactive States** โ€” Hover, press, focus, shimmer, and disabled states
203
+ โœ… **Custom Glass Hooks** โ€” Build your own components with shared glass behavior
204
+ โœ… **Small Package Surface** โ€” Exports only components, hooks, filters, and styles
205
+ โœ… **Framework Friendly** โ€” Works in Vite, Next.js, Remix, and standard React apps
206
+
207
+ ---
208
+
209
+ ## ๐Ÿ”ง Tech Stack
210
+
211
+ ### Runtime
212
+ - **React** โ€” Component model and rendering
213
+ - **React DOM** โ€” DOM integration
214
+ - **CSS** โ€” Liquid glass visuals, blur, masks, and animations
215
+
216
+ ### Development
217
+ - **TypeScript** โ€” Static types and public declaration files
218
+ - **Tsup** โ€” Library bundling for ESM and CommonJS
219
+ - **npm** โ€” Package publishing workflow
220
+
221
+ ---
222
+
223
+ ## ๐Ÿ“ฆ Package Exports
224
+
225
+ ### Components
226
+ - `GlassButton` โ€” Action button with liquid glass styling
227
+ - `GlassCard` โ€” Glass content container
228
+ - `GlassInput` โ€” Styled input surface
229
+ - `GlassSheet` โ€” Modal/bottom sheet component
230
+ - `GlassNav` โ€” Pill navigation component
231
+ - `LiquidGlassFilter` โ€” Advanced filter provider
232
+
233
+ ### Hooks
234
+ - `useGlassEffect` โ€” Generate reusable glass styles
235
+ - `useGlassAnimation` โ€” Track interactive component states
236
+
237
+ ### Styles
238
+ - `@zakisheriff/liquid-glass/styles.css` โ€” Core stylesheet
239
+
240
+ ---
241
+
242
+ ## ๐Ÿงช Component Examples
243
+
244
+ ### GlassButton
245
+
246
+ ```tsx
247
+ <GlassButton size="lg" variant="default" shimmer onClick={handleClick}>
248
+ Get the App
249
+ </GlassButton>
250
+ ```
251
+
252
+ ### GlassCard
253
+
254
+ ```tsx
255
+ <GlassCard padding="24px" radius="20px" shimmer>
256
+ <p>Content goes here</p>
257
+ </GlassCard>
258
+ ```
259
+
260
+ ### GlassInput
261
+
262
+ ```tsx
263
+ <GlassInput
264
+ label="Email"
265
+ placeholder="you@example.com"
266
+ value={email}
267
+ onChange={(event) => setEmail(event.target.value)}
268
+ />
269
+ ```
270
+
271
+ ### GlassSheet
272
+
273
+ ```tsx
274
+ <GlassSheet open={isOpen} onClose={() => setIsOpen(false)}>
275
+ <h3>Sheet Content</h3>
276
+ <p>This slides up from the bottom.</p>
277
+ </GlassSheet>
278
+ ```
279
+
280
+ ### GlassNav
281
+
282
+ ```tsx
283
+ <GlassNav
284
+ items={[
285
+ { label: 'Home' },
286
+ { label: 'About' },
287
+ { label: 'Contact' },
288
+ ]}
289
+ activeIndex={activeTab}
290
+ onChange={setActiveTab}
291
+ />
292
+ ```
293
+
294
+ ---
295
+
296
+ ## ๐Ÿง  How It Works
297
+
298
+ Liquid Glass is built with a multi-layer CSS approach:
299
+
300
+ - **Surface Layer** โ€” Semi-transparent gradients and `backdrop-filter` create the frosted base.
301
+ - **Depth Shadows** โ€” Carefully layered `box-shadow` values create physical depth and press feedback.
302
+ - **Prismatic Border** โ€” Masked conic gradients create a refractive rim around the surface.
303
+ - **Shine Overlay** โ€” Animated light streaks simulate glints moving across the component.
304
+ - **Motion Curve** โ€” `cubic-bezier(0.25, 1, 0.5, 1)` keeps transitions soft and tactile.
305
+
306
+ ---
307
+
308
+ ## ๐ŸŒ Browser Support
309
+
310
+ โœ… **Chrome 89+**
311
+ โœ… **Edge 89+**
312
+ โœ… **Safari 15.4+**
313
+ โœ… **Firefox 103+**
314
+
315
+ ---
316
+
317
+ ## ๐Ÿ› ๏ธ Development
318
+
319
+ ### Clone the Repository
320
+
321
+ ```bash
322
+ git clone https://github.com/zakisheriff/Liquid-Glass.git
323
+ cd liquid-glass
324
+ ```
325
+
326
+ ### Install Dependencies
327
+
328
+ ```bash
329
+ npm install
330
+ ```
331
+
332
+ ### Run the Build
333
+
334
+ ```bash
335
+ npm run build
336
+ ```
337
+
338
+ ### Watch During Development
339
+
340
+ ```bash
341
+ npm run dev
342
+ ```
343
+
344
+ ---
345
+
346
+ ## ๐Ÿค Contributing
347
+
348
+ Contributions are welcome! Please feel free to open an issue or submit a Pull Request.
349
+
350
+ ---
351
+
352
+ ## ๐Ÿ“„ License
353
+
354
+ MIT License โ€” free to use in personal and commercial projects.
355
+
356
+ ---
357
+
358
+ ## โ˜•๏ธ Support the Project
359
+
360
+ If Liquid Glass helped you build a more beautiful interface or inspired your next project:
361
+
362
+ - Consider buying me a coffee
363
+ - It keeps development alive and motivates future updates
364
+
365
+ <div align="center">
366
+ <a href="https://buymeacoffee.com/zakisheriffw">
367
+ <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="60" width="217">
368
+ </a>
369
+ </div>
370
+
371
+ ---
372
+
373
+ <p align="center">
374
+ Made by <strong>Zaki Sheriff</strong>
375
+ </p>
376
+
377
+ <p align="center">
378
+ <em>Because interfaces should feel as good as they look.</em>
379
+ </p>