@ticatec/topside-elements 1.0.0

package/dist/layouts/box/Box.svelte

@@ -0,0 +1,104 @@
+<script lang="ts">
+    import type {Snippet} from 'svelte';
+
+    interface Props {
+        title?: string;
+        round?: boolean;
+        style?: string;
+        /** 内容区内联样式 */
+        content$style?: string;
+        theme?: string;
+        children?: Snippet;
+        header?: Snippet;
+        footer?: Snippet;
+    }
+
+    let {
+        title = '',
+        round = false,
+        style = '',
+        content$style = '',
+        theme,
+        children,
+        header,
+        footer
+    }: Props = $props();
+</script>
+
+<div class="topside-box" data-theme={theme} class:rounded={round} {style}>
+    {#if title || header}
+        <div class="box-header">
+            {#if header}
+                {@render header()}
+            {:else}
+                <div class="title">
+                    <span>{title}</span>
+                </div>
+            {/if}
+        </div>
+    {/if}
+    <div class="box-content" style={content$style}>
+        {#if children}
+            {@render children()}
+        {/if}
+    </div>
+    {#if footer}
+        <div class="box-footer">
+            {@render footer()}
+        </div>
+    {/if}
+</div>
+
+<style>
+    .topside-box {
+        display: flex;
+        position: relative;
+        box-sizing: border-box;
+        overflow: hidden;
+        flex-direction: column;
+        background-color: var(--topside-box-color-surface);
+        border: 1px solid var(--topside-box-color-border);
+        color: var(--topside-primary-color-font);
+    }
+
+    .topside-box.rounded {
+        border-radius: var(--topside-box-radius);
+    }
+
+    .box-header {
+        width: 100%;
+        position: relative;
+        background-color: var(--topside-box-color-header-surface);
+        color: var(--topside-box-color-header-title);
+        user-select: none;
+        overflow: hidden;
+    }
+
+    .box-header .title {
+        width: 100%;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        box-sizing: border-box;
+        padding: var(--topside-box-header-padding);
+        white-space: nowrap;
+        font-weight: var(--topside-box-header-font-weight, 600);
+    }
+
+    .box-footer {
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        width: 100%;
+        flex: 0 0 auto;
+        user-select: none;
+        background-color: var(--topside-box-color-footer-surface);
+        color: var(--topside-box-color-footer-title);
+        font-weight: var(--topside-box-footer-font-weight, normal);
+    }
+
+    .box-content {
+        flex: 1 1 auto;
+        position: relative;
+        overflow: hidden;
+    }
+</style>

package/dist/layouts/box/Box.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    title?: string;
+    round?: boolean;
+    style?: string;
+    /** 内容区内联样式 */
+    content$style?: string;
+    theme?: string;
+    children?: Snippet;
+    header?: Snippet;
+    footer?: Snippet;
+}
+declare const Box: import("svelte").Component<Props, {}, "">;
+type Box = ReturnType<typeof Box>;
+export default Box;

package/dist/layouts/box/README.md

@@ -0,0 +1,312 @@
+# Box Component
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `contentStyle` were removed in 5.1.0 (no compatibility aliases are kept).
+
+A bordered flex-column container with optional header / footer. The structural building block for cards, panels, and dashboard widgets — Box itself is intentionally minimal (no shadow, no padding); you add visuals via `style` / `content$style` and CSS variables.
+
+## Features
+
+- **Header from `title` string OR `header` snippet** — snippet wins when both are set
+- **Optional `footer` snippet** — usually for action buttons
+- **Default children** fill the middle (`flex: 1 1 auto`, `overflow: hidden`)
+- **Optional rounded corners** via `round` prop (sets `border-radius: var(--topside-box-radius)`)
+- **Outer wrapper clips overflow** — children can't spill out
+- **Per-section styling**: `style` on the outer wrapper, `content$style` on the content area only
+- **Theme hook**: `data-theme="{theme}"` on the outer wrapper
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Box from '@ticatec/topside-elements/Box';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Box from '@ticatec/topside-elements/Box';
+</script>
+
+<Box title="Card Title">
+  <p>This is the content area.</p>
+</Box>
+```
+
+> **Box has no built-in padding on the content area.** Wrap your content in its own padded container, or pass `content$style="padding: 16px;"`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `''` | Title text rendered inside `.box-header > .title`. Ignored when `header` snippet is provided. Empty string → header block is not rendered (unless `header` snippet is set). |
+| `round` | `boolean` | `false` | Adds the `rounded` class → `border-radius: var(--topside-box-radius)` |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper (`.topside-box`) |
+| `content$style` | `string` | `''` | Inline CSS on the content area (`.box-content`). Use this for padding so the header/footer aren't affected. |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper for scoped CSS overrides |
+| `header` | `Snippet \| undefined` | `undefined` | Custom header content. **Overrides `title` when both are set.** |
+| `children` | `Snippet \| undefined` | `undefined` | Main content |
+| `footer` | `Snippet \| undefined` | `undefined` | Footer content (typically action buttons) |
+
+## Header Precedence
+
+The header block renders when **either** `title` is non-empty **or** `header` snippet is provided. If both are set, **the snippet wins** and `title` is ignored:
+
+```svelte
+<!-- ✅ Title only -->
+<Box title="Hello">...</Box>
+
+<!-- ✅ Header snippet only -->
+<Box>
+  {#snippet header()}<h3>Custom Header</h3>{/snippet}
+  ...
+</Box>
+
+<!-- ⚠️ Both: title is IGNORED, header snippet renders -->
+<Box title="Ignored">
+  {#snippet header()}<h3>Custom Header</h3>{/snippet}
+  ...
+</Box>
+```
+
+If you want the title AND extra content in the header, render the title yourself inside the snippet.
+
+## Layout
+
+```text
+┌──────────────────────────────────┐
+│ .box-header        (if title/header) │  ← user-select: none, ellipsis on title
+├──────────────────────────────────┤
+│ .box-content       (flex 1, overflow: hidden)
+│   {children}                         │  ← NO built-in padding — add via content$style
+├──────────────────────────────────┤
+│ .box-footer        (if footer)       │  ← flex row, user-select: none
+└──────────────────────────────────┘
+```
+
+Built-in styles:
+
+```css
+.topside-box {
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  box-sizing: border-box;
+  overflow: hidden;                  /* children can't spill */
+  background-color: var(--topside-box-color-surface);
+  border: 1px solid var(--topside-box-color-border);
+  color: var(--topside-primary-color-font);
+}
+
+.topside-box.rounded { border-radius: var(--topside-box-radius); }
+
+.box-header {
+  width: 100%;
+  background-color: var(--topside-box-color-header-surface);
+  color: var(--topside-box-color-header-title);
+  user-select: none;
+  overflow: hidden;
+}
+
+.box-header .title {
+  width: 100%;
+  padding: var(--topside-box-header-padding);
+  white-space: nowrap;               /* single line */
+  text-overflow: ellipsis;           /* truncates with … */
+  font-weight: var(--topside-box-header-font-weight, 600);
+}
+
+.box-content {
+  flex: 1 1 auto;
+  position: relative;
+  overflow: hidden;
+}
+
+.box-footer {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  width: 100%;
+  flex: 0 0 auto;
+  user-select: none;
+  background-color: var(--topside-box-color-footer-surface);
+  color: var(--topside-box-color-footer-title);
+  font-weight: var(--topside-box-footer-font-weight, normal);
+}
+```
+
+## Examples
+
+### Title + Content
+
+```svelte
+<Box title="Information">
+  <p>This is some important information.</p>
+</Box>
+```
+
+### Title + Content + Footer (action buttons)
+
+```svelte
+<script>
+  import Box from '@ticatec/topside-elements/Box';
+  import ActionBar from '@ticatec/topside-elements/ActionBar';
+</script>
+
+<Box title="User Profile" content$style="padding: 16px;">
+  <p>User information and details</p>
+
+  {#snippet footer()}
+    <ActionBar
+      style="width: 100%; justify-content: flex-end; padding: 8px 12px;"
+      buttons={[
+        { label: 'Cancel', handler: cancel },
+        { label: 'Save',   type: 'primary', handler: save }
+      ]}
+    />
+  {/snippet}
+</Box>
+```
+
+### Custom Header (title + action button)
+
+```svelte
+<Box content$style="padding: 16px;">
+  {#snippet header()}
+    <div style="display: flex; justify-content: space-between; align-items: center; padding: 8px 16px;">
+      <h3>Sales Overview</h3>
+      <Button type="primary" label="Export" onclick={exportReport} />
+    </div>
+  {/snippet}
+
+  <!-- content -->
+  <p>...</p>
+</Box>
+```
+
+### Rounded Card with Shadow
+
+```svelte
+<Box
+  title="Rounded Card"
+  round
+  style="box-shadow: 0 2px 8px rgba(0,0,0,0.08);"
+  content$style="padding: 16px;"
+>
+  <p>This card has rounded corners and a soft shadow.</p>
+</Box>
+```
+
+### Dashboard Widget (header + content + footer)
+
+```svelte
+<script>
+  import Box from '@ticatec/topside-elements/Box';
+</script>
+
+<Box round style="height: 100%;">
+  {#snippet header()}
+    <div style="display: flex; justify-content: space-between; align-items: center; padding: 8px 16px;">
+      <h3>Sales Overview</h3>
+      <select onchange={changeRange}>
+        <option value="this-month">This Month</option>
+        <option value="last-month">Last Month</option>
+      </select>
+    </div>
+  {/snippet}
+
+  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 16px; padding: 16px;">
+    <div>
+      <div style="font-size: 24px; font-weight: bold;">$12,345</div>
+      <div style="color: gray;">Revenue</div>
+    </div>
+    <div>
+      <div style="font-size: 24px; font-weight: bold;">89</div>
+      <div style="color: gray;">Orders</div>
+    </div>
+  </div>
+
+  {#snippet footer()}
+    <a href="/reports/sales" style="padding: 8px 16px; display: inline-block;">
+      View Detailed Report →
+    </a>
+  {/snippet}
+</Box>
+```
+
+### Footer-Only (no header)
+
+```svelte
+<Box content$style="padding: 16px;">
+  <p>Content with a footer but no header.</p>
+
+  {#snippet footer()}
+    <small style="padding: 8px 16px; color: #6b7280;">Last updated 2 mins ago</small>
+  {/snippet}
+</Box>
+```
+
+## Theming via CSS Variables
+
+```css
+:root {
+  /* Outer wrapper */
+  --topside-box-color-surface: #ffffff;        /* content background */
+  --topside-box-color-border:  #e5e7eb;        /* 1px border */
+  --topside-primary-color-font: #374151;       /* base text color */
+  --topside-box-radius: 8px;                    /* applied only when round=true */
+
+  /* Header */
+  --topside-box-color-header-surface: #f9fafb;
+  --topside-box-color-header-title:   #374151;
+  --topside-box-header-padding: 12px 16px;
+  --topside-box-header-font-weight: 600;
+
+  /* Footer */
+  --topside-box-color-footer-surface: #f9fafb;
+  --topside-box-color-footer-title:   #6b7280;
+  --topside-box-footer-font-weight: normal;
+}
+
+[data-theme='dark'] {
+  --topside-box-color-surface: #1f2937;
+  --topside-box-color-border:  #374151;
+  --topside-box-color-header-surface: #111827;
+  --topside-box-color-header-title:   #f9fafb;
+  --topside-box-color-footer-surface: #111827;
+  --topside-box-color-footer-title:   #9ca3af;
+}
+```
+
+## Behavior Notes
+
+- **`overflow: hidden` is everywhere**: outer wrapper, `.box-header`, `.box-content`. Long content is clipped, not scrolled. Add your own `overflow: auto` inside children if you need scrolling.
+- **Title is single-line** (`white-space: nowrap; text-overflow: ellipsis`). Long titles show `…` instead of wrapping.
+- **Header & footer disable text selection** (`user-select: none`) — they're meant for labels/actions, not copyable content.
+- **No shadow by default.** Pass `style="box-shadow: ..."` for a card look.
+- **No content padding by default.** Use `content$style="padding: ..."` so the header/footer aren't affected.
+
+## Accessibility
+
+- The outer wrapper is a plain `<div>` with no role. If the Box represents a landmark (e.g. a `complementary` sidebar), add `role="..."` yourself.
+- For a true "card" semantic, consider wrapping with `<section>` and giving the header `aria-label` or using a heading element inside the `header` snippet.
+- Title text inside the default `.title` div is not heading-tagged — search engines and screen readers won't treat it as a heading. Use the `header` snippet with `<h2>`/`<h3>` for proper document outline.
+
+## Best Practices
+
+1. **Add your own content padding** via `content$style="padding: ..."`. Box intentionally doesn't pad so the header/footer edges can sit flush with the border.
+2. **Use `header` snippet over `title`** as soon as you need icons, action buttons, or a different layout — the snippet takes precedence anyway, so it's clearer.
+3. **Reserve the footer for actions**, not extra content — it has `user-select: none` and is visually separated by background.
+4. **For scrollable content**, wrap your content in its own `<div style="overflow: auto; height: 100%">`. Box's `overflow: hidden` will clip but won't scroll.
+5. **Use `round` for cards**, leave it off for full-width panels (where rounded corners look odd against neighbors).
+6. **Long titles will be truncated with `…`** by default. If you need them to wrap, use the `header` snippet with your own styling.
+
+## Related Components
+
+- [ActionBar](../action_bar/README.md) — often placed in the `footer` snippet
+- [AppTopBar](../app_top_bar/README.md) — top-bar counterpart for app shells