@hoangyell/gallery 1.0.3 → 1.0.6

package/README.md

@@ -2,9 +2,32 @@
 
 [Astro](https://astro.build/) image gallery component with lightbox, pyramid multi-row layout, and accessible controls.
 
+**Live demo → [gallery.hoangyell.com](https://gallery.hoangyell.com)**
+
+<p align="center">
+  <a href="https://gallery.hoangyell.com">
+    <img
+      src="https://raw.githubusercontent.com/HoangYell/hoangyell-gallery/main/packages/astro/docs/site-hero.jpg"
+      alt="@hoangyell/gallery landing page hero — The friendly Astro image gallery"
+      width="720"
+    />
+  </a>
+</p>
+
+<p align="center">
+  <em>Click any image to open the lightbox — keyboard arrows, swipe, ESC to close.</em>
+  <br />
+  <img
+    src="https://raw.githubusercontent.com/HoangYell/hoangyell-gallery/main/packages/astro/docs/gallery-lightbox.jpg"
+    alt="Lightbox view with page indicator, close button, and next-image arrow"
+    width="640"
+  />
+</p>
+
 ## Features
 
 - **Pyramid layout** — distribute images across rows with `rows` prop
+- **Two fit modes** — `cover` (default, uniform photo grid) or `contain` (natural aspect, for diagrams and tall portraits)
 - **Lightbox** — click to open, keyboard arrows, swipe, ESC to close
 - **Corner rounding** — only the four outer corners of each group are rounded
 - **Hover zoom** — image scales inside its cell without changing layout
@@ -57,9 +80,46 @@ import { Gallery } from "@hoangyell/gallery";
 | `rows` | `number` | auto (~3 per row) | Number of visual rows |
 | `orientation` | `"landscape" \| "portrait"` | `"landscape"` | Item aspect ratio hint |
 | `scale` | `number` | `1` | Gallery width scale (0–1) |
-| `fit` | `ObjectFit` | `"cover"` | Default CSS object-fit |
+| `fit` | `ObjectFit` | `"cover"` | Default CSS object-fit — see Fit modes below |
 | `class` | `string` | — | Extra wrapper class |
 
+## Fit modes
+
+The `fit` prop controls **both** the image's `object-fit` **and** the
+container's aspect ratio. Pick the right one for your content:
+
+| Mode | What you get | When to use |
+|---|---|---|
+| `"cover"` (default) | Uniform 4:3 grid (1:1 on mobile). Images are cropped to fill. | Photo galleries — travel, products, faces. The Pinterest aesthetic. |
+| `"contain"` | Container hugs each image's natural aspect ratio. No cropping. | Diagrams, charts, screenshots, comics, tall portraits. |
+
+Set it at the gallery level:
+
+```mdx
+<Gallery items={["/diagram.png"]} rows={1} fit="contain" />
+```
+
+Or per-item (mix and match in the same gallery):
+
+```mdx
+<Gallery
+  items={[
+    "/cover-photo.jpg",
+    { src: "/architecture-diagram.png", fit: "contain" },
+  ]}
+/>
+```
+
+## Dark mode
+
+The component auto-themes via three mechanisms (last one wins):
+
+1. `prefers-color-scheme: dark` — OS preference (default).
+2. `<html class="dark">` or `<html data-theme="dark">` — Tailwind-style class toggle.
+3. `<html class="light">` or `<html data-theme="light">` — explicit light theme override.
+
+This means it Just Works™ with manual theme toggles **and** OS preference.
+
 ## Customization
 
 Override CSS custom properties on `.hy-gallery`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoangyell/gallery",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "description": "Astro image gallery with lightbox, pyramid multi-row layout, and accessible controls.",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,7 @@
     "photo-gallery"
   ],
   "author": "Hoang Yell <hoangyell@gmail.com> (https://hoangyell.com)",
-  "homepage": "https://github.com/HoangYell/hoangyell-gallery#readme",
+  "homepage": "https://gallery.hoangyell.com",
   "repository": {
     "type": "git",
     "url": "https://github.com/HoangYell/hoangyell-gallery.git",

package/src/Gallery.astro

@@ -100,6 +100,7 @@ if (resolvedRows <= 1 || galleryItems.length <= 1) {
       class={`hy-gallery ${className}`}
       data-hy-gallery
       data-orientation={orientation}
+      data-fit={fit}
       style={scale !== 1 ? `width: ${scale * 100}%; margin: 2rem auto;` : undefined}
     >
       {groupedItems.map((group, rowIdx) => {
@@ -124,6 +125,7 @@ if (resolvedRows <= 1 || galleryItems.length <= 1) {
                   class={`hy-gallery-item ${cornerClasses}`}
                   data-zoom-src={item.src}
                   data-alt={item.alt}
+                  data-fit={item.fit}
                   aria-label={
                     item.alt ? `View full size: ${item.alt}` : "View full size image"
                   }
@@ -159,6 +161,7 @@ if (resolvedRows <= 1 || galleryItems.length <= 1) {
     --hy-gallery-control-bg: rgba(255, 255, 255, 0.95);
   }
 
+  /* OS-level dark preference. */
   @media (prefers-color-scheme: dark) {
     .hy-gallery {
       --hy-gallery-bg: #0f172a;
@@ -170,6 +173,28 @@ if (resolvedRows <= 1 || galleryItems.length <= 1) {
     }
   }
 
+  /* Explicit light theme on any ancestor wins over OS preference.
+     Supports Tailwind-style `.light` class and `[data-theme="light"]`. */
+  :where(.light, [data-theme="light"]) .hy-gallery {
+    --hy-gallery-bg: #f8fafc;
+    --hy-gallery-overlay-bg: rgba(255, 255, 255, 0.7);
+    --hy-gallery-accent: #2563eb;
+    --hy-gallery-border: #e2e8f0;
+    --hy-gallery-text: #334155;
+    --hy-gallery-control-bg: rgba(255, 255, 255, 0.95);
+  }
+
+  /* Explicit dark theme on any ancestor wins over OS preference.
+     Supports Tailwind-style `.dark` class and `[data-theme="dark"]`. */
+  :where(.dark, [data-theme="dark"]) .hy-gallery {
+    --hy-gallery-bg: #0f172a;
+    --hy-gallery-overlay-bg: rgba(2, 6, 23, 0.8);
+    --hy-gallery-accent: #60a5fa;
+    --hy-gallery-border: #334155;
+    --hy-gallery-text: #e2e8f0;
+    --hy-gallery-control-bg: rgba(30, 41, 59, 0.95);
+  }
+
   .hy-gallery {
     display: flex;
     flex-direction: column;
@@ -240,6 +265,16 @@ if (resolvedRows <= 1 || galleryItems.length <= 1) {
     }
   }
 
+  /* fit="contain" — show the whole image at its natural aspect ratio.
+     Drops the forced 4:3 / 1:1 container so diagrams, charts, screenshots,
+     and tall portraits render fully without cropping or letterboxing.
+     Applied either at the wrapper (global) or per-item via data-fit. */
+  .hy-gallery[data-fit="contain"] .hy-gallery-item,
+  .hy-gallery .hy-gallery-item[data-fit="contain"] {
+    aspect-ratio: auto;
+    background: transparent;
+  }
+
   .hy-gallery-img {
     position: absolute;
     inset: 0;
@@ -256,6 +291,16 @@ if (resolvedRows <= 1 || galleryItems.length <= 1) {
     transition: transform 0.4s cubic-bezier(0.4, 0, 0.2, 1);
   }
 
+  /* In contain mode the image is the primary content — let it drive height
+     instead of being absolutely positioned inside a fixed-aspect box. */
+  .hy-gallery[data-fit="contain"] .hy-gallery-img,
+  .hy-gallery .hy-gallery-item[data-fit="contain"] .hy-gallery-img {
+    position: static;
+    width: 100%;
+    height: auto;
+    inset: auto;
+  }
+
   .hy-gallery-item:hover .hy-gallery-img,
   .hy-gallery-item:focus-visible .hy-gallery-img {
     will-change: transform;