@juv/codego-react-ui 3.1.5 → 3.1.8

package/README.md

@@ -201,6 +201,173 @@ input[type="datetime-local"]::-webkit-inner-spin-button {
 }
 ```
 
+## in LARAVEL "resources\css\app.css"
+```css
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Inter:wght@400;500;600&display=swap');
+@import "tailwindcss";
+
+@source "../../resources/js";
+@source "../../node_modules/@juv/codego-react-ui/dist";
+
+@theme {
+  --font-sans: "Space Grotesk", "Inter", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace;
+
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-hover: var(--primary-hover);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-hover: var(--secondary-hover);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-info: var(--info);
+  --color-info-hover: var(--info-hover);
+  --color-info-foreground: var(--info-foreground);
+  --color-warning: var(--warning);
+  --color-warning-hover: var(--warning-hover);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-danger: var(--danger);
+  --color-danger-hover: var(--danger-hover);
+  --color-danger-foreground: var(--danger-foreground);
+  --color-success: var(--success);
+  --color-success-hover: var(--success-hover);
+  --color-success-foreground: var(--success-foreground);
+  --radius: var(--radius);
+}
+
+@layer base {
+  :root {
+    --background: #ffffff;
+    --foreground: #09090b;
+    --card: #ffffff;
+    --card-foreground: #09090b;
+    --popover: #ffffff;
+    --popover-foreground: #09090b;
+    --primary: #6366f1; /* Indigo 500 */
+    --primary-hover: #4f46e5;
+    --primary-foreground: #ffffff;
+    --secondary: #f4f4f5;
+    --secondary-hover: #e4e4e7;
+    --secondary-foreground: #18181b;
+    --info: #3b82f6; /* Blue 500 */
+    --info-hover: #2563eb;
+    --info-foreground: #ffffff;
+    --warning: #f59e0b; /* Amber 500 */
+    --warning-hover: #d97706;
+    --warning-foreground: #ffffff;
+  --danger: #ef4444; /* Red 500 */
+  --danger-hover: #dc2626;
+  --danger-foreground: #ffffff;
+  --success: #22c55e; /* Green 500 */
+  --success-hover: #16a34a;
+  --success-foreground: #ffffff;
+  --muted: #f4f4f5;
+    --muted-foreground: #71717a;
+    --accent: #f4f4f5;
+    --accent-foreground: #18181b;
+    --destructive: #ef4444;
+    --destructive-foreground: #ffffff;
+    --border: #e4e4e7;
+    --input: #e4e4e7;
+    --ring: var(--primary);
+    --radius: 0.75rem;
+  }
+
+  .dark {
+    --background: #030303; /* Deep black */
+    --foreground: #ededed;
+    --card: #0a0a0a; /* Slightly lighter black */
+    --card-foreground: #ededed;
+    --popover: #0a0a0a;
+    --popover-foreground: #ededed;
+    --primary: #8b5cf6; /* Neon Violet */
+    --primary-hover: #7c3aed;
+    --primary-foreground: #ffffff;
+    --secondary: #171717;
+    --secondary-hover: #262626;
+    --secondary-foreground: #ededed;
+    --info: #3b82f6;
+    --info-hover: #2563eb;
+    --info-foreground: #ffffff;
+    --warning: #f59e0b;
+    --warning-hover: #d97706;
+    --warning-foreground: #ffffff;
+  --danger: #ef4444;
+  --danger-hover: #dc2626;
+  --danger-foreground: #ffffff;
+  --success: #22c55e;
+  --success-hover: #16a34a;
+  --success-foreground: #ffffff;
+  --muted: #171717;
+    --muted-foreground: #a1a1aa;
+    --accent: #1f1f2e; /* Subtle purple tint */
+    --accent-foreground: #c4b5fd;
+    --destructive: #7f1d1d;
+    --destructive-foreground: #ededed;
+    --border: #1f1f1f;
+    --input: #1f1f1f;
+    --ring: var(--primary);
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-feature-settings: "rlig" 1, "calt" 1;
+  }
+}
+
+@layer utilities {
+  .glass {
+    @apply bg-background/60 backdrop-blur-xl border border-white/10;
+  }
+  .dark .glass {
+    @apply bg-black/40 border-white/5;
+  }
+  .text-gradient {
+    background: linear-gradient(to right, var(--primary), var(--info));
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+  }
+  .glow {
+    box-shadow: 0 0 20px -5px var(--primary);
+  }
+}
+/* Hide calendar icon (Chrome, Edge, Safari) */
+input[type="datetime-local"]::-webkit-calendar-picker-indicator {
+  display: none;
+  -webkit-appearance: none;
+}
+
+/* Optional: remove clear (X) button */
+input[type="datetime-local"]::-webkit-clear-button {
+  display: none;
+}
+
+/* Optional: remove spin buttons */
+input[type="datetime-local"]::-webkit-inner-spin-button {
+  display: none;
+}
+
+```
 ### 3. Lucide React (icons)
 
 ```bash
@@ -257,6 +424,40 @@ import { Button, Card, Modal } from "@juv/codego-react-ui"
 
 ---
 
+## Form Validation Props
+
+All form input components support two shared validation props:
+
+| Prop | Type | Description |
+|---|---|---|
+| `required` | `boolean` | Marks the field as required. Shows a `*` indicator next to the label. Also sets `aria-required` on the underlying input. |
+| `error` | `string` | External error message rendered below the field in destructive color. Also sets `aria-invalid` on the underlying input. |
+
+Applies to: `Input`, `Select`, `Textarea`, `Checkbox`, `ToggleSwitch`, `RadioGroup`, `Combobox`, `TagInput`, `OtpInput`, `ColorPicker`, `Slider`, `RangeSlider`, `FileUpload`.
+
+```tsx
+// Required field with * indicator
+<Input label="Email" required placeholder="you@example.com" />
+
+// External error message (e.g. from server validation)
+<Input label="Email" required error="Email is already taken" />
+
+// Works on all form components
+<Select label="Role" required error="Please select a role" options={options} />
+<Checkbox inline label="Accept terms" required error="You must accept the terms" />
+<ToggleSwitch inline label="Enable 2FA" required />
+<Textarea label="Bio" required error="Bio is required" />
+<RadioGroup options={plans} required error="Please select a plan" />
+<Combobox options={frameworks} required error="Please select a framework" />
+<TagInput required error="At least one tag is required" />
+<OtpInput length={6} required error="Please enter the code" />
+<ColorPicker required error="Please select a color" />
+<Slider label="Volume" required error="Please set a value" />
+<FileUpload label="Avatar" required error="Please upload a file" />
+```
+
+---
+
 ## Components
 
 | Component | Export(s) |
@@ -265,6 +466,7 @@ import { Button, Card, Modal } from "@juv/codego-react-ui"
 | Avatar Stack | `AvatarStack` |
 | Badge | `Badge` |
 | Breadcrumb | `Breadcrumb` |
+| Bulletin Board | `BulletinBoard`, `BulletinPreview`, `useServerBulletin` |
 | Button | `Button` |
 | Calendar | `Calendar` |
 | Card | `Card` |
@@ -320,6 +522,105 @@ import { Button, Card, Modal } from "@juv/codego-react-ui"
 
 ---
 
+## BulletinBoard Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `BulletinItem[]` | — | ✓ Array of bulletin post items. |
+| `layout` | `"grid" \| "list" \| "masonry"` | `"grid"` | Board layout mode. |
+| `columns` | `1 \| 2 \| 3 \| 4` | `3` | Number of grid columns (responsive). |
+| `variant` | `"card" \| "minimal" \| "bordered"` | `"card"` | Visual style of each post card. |
+| `searchable` | `boolean` | `false` | Show a search input above the board. |
+| `filterable` | `boolean` | `false` | Show category filter chips above the board. |
+| `categories` | `string[]` | | Explicit category list. Auto-derived from items if omitted. |
+| `title` | `ReactNode` | `"Bulletin Board"` | Board header title. |
+| `headerAction` | `ReactNode` | | Trailing element in the board header (e.g. a New Post button). |
+| `showHeader` | `boolean` | `true` | Show or hide the board header bar. |
+| `emptyMessage` | `ReactNode` | `"No posts found."` | Content shown when the filtered list is empty. |
+| `loading` | `boolean` | `false` | Show skeleton cards instead of real content. |
+| `loadingCount` | `number` | `6` | Number of skeleton cards to render while loading. |
+| `preview` | `boolean` | `false` | Open a `BulletinPreview` modal when a card is clicked. |
+| `onEdit` | `(item: BulletinItem) => void` | | Called when the Edit button is clicked inside the preview. |
+| `onDelete` | `(item: BulletinItem) => void` | | Called after a successful delete (or when no `deleteBaseUrl` is set). |
+| `deleteBaseUrl` | `string` | | Base URL for built-in `DELETE {baseUrl}/{id}/delete` request. |
+| `deleteIdKey` | `string` | `"id"` | Item key used as the id segment in the delete URL. |
+| `serverPagination` | `BulletinServerPaginationProp \| null` | | Pass the `serverPagination` from `useServerBulletin` to enable server-driven pagination. |
+| `onItemClick` | `(item: BulletinItem) => void` | | Fired when a card is clicked (ignored when `preview=true`). |
+| `className` | `string` | | Additional CSS classes on the outer wrapper. |
+
+### BulletinPreview Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `item` | `BulletinItem` | ✓ | The bulletin item to display. |
+| `onClose` | `() => void` | ✓ | Called when the modal is dismissed. |
+| `onEdit` | `(item: BulletinItem) => void` | | Show an Edit button; called when clicked. |
+| `onDelete` | `(item: BulletinItem) => void` | | Show a Delete button; called when clicked. |
+
+### useServerBulletin Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `url` | `string` | ✓ | API endpoint. `?page=N` appended automatically. |
+| `params` | `Record<string, string \| number>` | | Extra query params merged on every request. |
+| `encrypt` | `boolean` | | Expect a Laravel-encrypted response payload. |
+| `key` | `string` | | Laravel `APP_KEY` for decryption. |
+| `decryptPayloadLog` | `boolean` | | Log the decrypted payload to the console. |
+| `transform` | `(row: any) => BulletinItem` | | Map a raw API row to a `BulletinItem`. |
+
+### useServerBulletin Return
+
+| Field | Type | Description |
+|---|---|---|
+| `items` | `BulletinItem[]` | Fetched (and optionally transformed) items. |
+| `loading` | `boolean` | `true` while the request is in-flight. |
+| `error` | `string \| null` | Error message if the request failed. |
+| `pagination` | `ServerPagination \| null` | Raw pagination metadata. |
+| `serverPagination` | `BulletinServerPaginationProp \| null` | Pass directly as `<BulletinBoard serverPagination={...} />`. |
+| `goToPage` | `(page: number) => void` | Navigate to a specific page. |
+| `reload` | `() => void` | Re-fetch the current page (e.g. after a delete). |
+
+### useServerBulletin Example
+
+```tsx
+import { BulletinBoard, useServerBulletin } from "@juv/codego-react-ui"
+
+function AnnouncementsPage() {
+  const { items, loading, serverPagination, reload } = useServerBulletin({
+    url: "/api/bulletins",
+    params: { per_page: 9 },
+    transform: (row) => ({
+      id: row.id,
+      title: row.subject,
+      body: row.content,
+      author: row.posted_by,
+      date: row.created_at,
+      category: row.department,
+      priority: row.level,
+      pinned: row.is_pinned,
+      tags: row.tags ?? [],
+    }),
+  })
+
+  return (
+    <BulletinBoard
+      items={items}
+      loading={loading}
+      serverPagination={serverPagination}
+      columns={3}
+      searchable
+      filterable
+      preview
+      onEdit={(item) => openEditModal(item)}
+      deleteBaseUrl="/api/bulletins"
+      onDelete={() => reload()}
+    />
+  )
+}
+```
+
+---
+
 ## LeafletMap Props
 
 | Prop | Type | Default | Description |