astro-better-details 0.1.0

package/Details.astro

@@ -0,0 +1,70 @@
+---
+interface Props {
+  open?: boolean;
+  class?: string;
+}
+
+const { open, class: cls } = Astro.props;
+---
+
+<details class:list={['abt-details', cls]} open={open}>
+  <summary class="abt-details-summary">
+    <span class="abt-details-title"><slot name="title" /></span>
+    <svg class="abt-details-chevron" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+      <path fill-rule="evenodd" d="M5.23 7.21a.75.75 0 011.06.02L10 11.168l3.71-3.938a.75.75 0 111.08 1.04l-4.25 4.5a.75.75 0 01-1.08 0l-4.25-4.5a.75.75 0 01.02-1.06z" clip-rule="evenodd" />
+    </svg>
+  </summary>
+  <div class="abt-details-body">
+    <slot />
+  </div>
+</details>
+
+<style is:global>
+  .abt-details {
+    border: 1px solid var(--abt-details-border, #d1d5db);
+    border-radius: 0.375rem;
+    margin: 1rem 0;
+    overflow: hidden;
+  }
+
+  .abt-details-summary {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem;
+    padding: 0.75rem 1rem;
+    cursor: pointer;
+    list-style: none;
+    background: var(--abt-details-summary-bg, #f9fafb);
+    font-weight: 500;
+    user-select: none;
+  }
+
+  .abt-details-summary::-webkit-details-marker { display: none; }
+  .abt-details-summary::marker { display: none; }
+
+  .abt-details[open] > .abt-details-summary {
+    border-bottom: 1px solid var(--abt-details-border, #d1d5db);
+  }
+
+  .abt-details-title {
+    flex: 1;
+    min-width: 0;
+  }
+
+  .abt-details-chevron {
+    width: 1.25rem;
+    height: 1.25rem;
+    flex-shrink: 0;
+    color: var(--abt-details-chevron, #9ca3af);
+    transition: transform 0.2s ease;
+  }
+
+  .abt-details[open] .abt-details-chevron {
+    transform: rotate(180deg);
+  }
+
+  .abt-details-body {
+    padding: 1rem;
+  }
+</style>

package/README.md

@@ -0,0 +1,85 @@
+# astro-better-details
+
+Expandable `<details>` / `<summary>` disclosure component for Astro MDX. No JavaScript required -- the browser handles expand/collapse natively. The chevron animates with CSS.
+
+## Installation
+
+```shell
+npm install astro-better-details
+```
+
+## Basic usage
+
+```mdx
+import Details from 'astro-better-details/Details.astro';
+
+<Details>
+  <span slot="title">What is this?</span>
+  This is the expanded content. It can contain any Markdown or MDX.
+</Details>
+```
+
+The `title` slot holds the always-visible summary label. The default slot holds the body content shown when expanded.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | `false` | Render the component already expanded |
+| `class` | `string` | -- | Additional CSS class(es) applied to the `<details>` element |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `title` (named) | Label shown in the clickable summary bar |
+| default | Body content, shown when expanded |
+
+The title slot accepts any inline content -- plain text, backtick code, links, or JSX components.
+
+## Theming
+
+The component uses CSS custom properties for all visual values. Override them on `.abt-details` or any parent selector to match your brand:
+
+| Property | Default | Controls |
+|----------|---------|----------|
+| `--abt-details-border` | `#d1d5db` | Border color around the whole component and between summary/body |
+| `--abt-details-summary-bg` | `#f9fafb` | Background of the summary bar |
+| `--abt-details-chevron` | `#9ca3af` | Chevron icon color |
+
+Example -- purple light mode, orange dark mode to match a common docs site palette:
+
+```css
+.abt-details {
+  --abt-details-border:     #ddd6fe;
+  --abt-details-summary-bg: #f5f3ff;
+  --abt-details-chevron:    #7c3aed;
+}
+
+.dark .abt-details {
+  --abt-details-border:     #1c0e00;
+  --abt-details-summary-bg: #0f0f0f;
+  --abt-details-chevron:    #fb923c;
+}
+```
+
+If your project uses a `data-theme` attribute instead of a `.dark` class, adjust the selector accordingly.
+
+## Code blocks inside Details
+
+The body slot renders its content as raw HTML. Code block titles (the `title="..."` meta from `astro-better-code-blocks`) render correctly because that package's CSS targets `.code-figure` globally. Do not add a `.prose` class to the body if you use Tailwind Typography -- the typography plugin styles `<figcaption>` as italic, which would override the `font-style: normal` on code titles.
+
+If your site needs prose-style typography inside the body, apply it via a wrapper element inside the slot rather than on the component itself:
+
+```mdx
+<Details>
+  <span slot="title">Example</span>
+  <div class="prose">
+    Content here gets prose styling.
+  </div>
+</Details>
+```
+
+## Accessibility
+
+The component renders a native `<details>` / `<summary>` element pair. Screen readers expose this as a disclosure widget with the summary as the interactive label. No ARIA attributes need to be added manually.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "astro-better-details",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Expandable details/disclosure component for Astro",
+  "author": "Nathan Contino <ncontino@lambdalatitudinarians.org>",
+  "license": "MIT",
+  "keywords": ["astro", "astro-component", "details", "disclosure"],
+  "exports": {
+    "./Details.astro": "./Details.astro"
+  },
+  "files": ["Details.astro"],
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  }
+}