@ozankurt/file-chips 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.1.0
+
+- `@fileChipsStyles` and `@fileChipsScripts` add the published file's modification time as `?v=`, and the script tag carries the Vite CSP nonce.
+- TypeScript declarations (`dist/file-chips.d.ts`), including the `file-chips:change` event.
+- CI tests Laravel 11, 12 and 13.
+
 ## 1.0.0
 
 - Initial release: framework-free file chips with a preview popover and mark-for-removal (`@ozankurt/file-chips` on npm), and a Laravel `<x-file-chips>` Blade component with optional Spatie Media Library support (`ozankurt/laravel-file-chips`).

package/README.md

@@ -2,6 +2,8 @@
 
 Compact file chips for forms and detail pages. Each chip opens a preview popover with a thumbnail, file details and View / Download links, and can mark the file for removal: a hidden input is added to your form and your server deletes the file on save.
 
+![An expense claim form with six file chips; the chip for client-dinner-receipt.jpg has opened a popover with a receipt thumbnail, the file size and date, a note, and View, Download and Remove on save buttons.](docs/images/popover-light.png)
+
 - **JavaScript + CSS** on npm as [`@ozankurt/file-chips`](https://www.npmjs.com/package/@ozankurt/file-chips): no dependencies, no framework, about 3 KB minified.
 - **Laravel** on Packagist as `ozankurt/laravel-file-chips`: a `<x-file-chips>` Blade component that renders the markup, with optional [Spatie Media Library](https://spatie.be/docs/laravel-medialibrary) support, and ships the same built JS and CSS.
 
@@ -26,6 +28,8 @@ In your layout:
 </body>
 ```
 
+Both URLs carry the published file's modification time (`?v=...`), so browsers fetch the new files after you upgrade and publish the assets again. The script tag gets your CSP nonce when the app uses `Vite::useCspNonce()`.
+
 In a form:
 
 ```blade
@@ -46,6 +50,10 @@ foreach ($request->input('delete_media_ids', []) as $id) {
 
 Always scope the deletion to the owning model as above; the ids come from the browser.
 
+Marking a file adds the hidden input and strikes the chip through until the form is saved:
+
+![The PDF chip is outlined in red with its name struck through, and its popover shows a red Marked button.](docs/images/marked-light.png)
+
 ### Props
 
 | Prop | Type | Default | Description |
@@ -184,6 +192,8 @@ Every colour, radius and size is a CSS custom property. Override them on `:root`
 }
 ```
 
+![The same form and popover in a dark theme set only through the custom properties above.](docs/images/popover-dark.png)
+
 Full list: `--fc-font-size`, `--fc-gap`, `--fc-radius`, `--fc-chip-max-width`, `--fc-chip-bg`, `--fc-chip-bg-hover`, `--fc-border`, `--fc-text`, `--fc-muted`, `--fc-danger`, `--fc-danger-bg`, `--fc-primary`, `--fc-primary-text`, `--fc-focus`, `--fc-ext-bg`, `--fc-popover-width`, `--fc-popover-bg`, `--fc-popover-border`, `--fc-popover-radius`, `--fc-popover-shadow`, `--fc-popover-z`, `--fc-thumb-size`, `--fc-thumb-bg`.
 
 ## Development
@@ -193,8 +203,19 @@ npm install && composer install
 npm test            # JS (Vitest + happy-dom)
 vendor/bin/pest     # PHP
 npm run build       # rebuild dist/, which is committed
+npm run examples    # the showcase on http://localhost:5183/showcase.html
+npm run screenshots # recapture docs/images/ from the showcase
+npm run typecheck   # the TypeScript declarations
 ```
 
+CI runs the PHP suite on PHP 8.3 with Laravel 11, and PHP 8.4 with Laravel 12 and 13, plus the JS tests, the typecheck and a check that the committed `dist/` matches the sources.
+
+### TypeScript
+
+`dist/file-chips.d.ts` types the JS API and the `file-chips:change` event, so `import FileChips from '@ozankurt/file-chips'` is typed in TypeScript and editors.
+
+The showcase takes `?scheme=light|dark` and `?scene=popover|marked`.
+
 ## License
 
 MIT

package/dist/file-chips.d.ts

@@ -0,0 +1,43 @@
+// Type declarations for @ozankurt/file-chips.
+
+export interface InitOptions {
+    /** Handle chips inside this element only. Default: the whole document. */
+    root?: Document | Element;
+}
+
+/** Detail of the bubbling `file-chips:change` event dispatched on a chip. */
+export interface FileChipChangeDetail {
+    id: string;
+    input: string;
+    marked: boolean;
+}
+
+/**
+ * Start handling chips inside `root`. A root that is already handled, itself
+ * or through an ancestor, is a no-op. Returns a function that stops handling it.
+ */
+export declare function init(options?: InitOptions): () => void;
+export declare function close(): void;
+export declare function getOpen(): HTMLElement | null;
+export declare function position(chip: HTMLElement, popover: HTMLElement): void;
+
+declare const FileChips: {
+    init: typeof init;
+    /** Open a chip's popover; returns the popover, or null when it has none. */
+    open(chip: HTMLElement): HTMLElement | null;
+    close: typeof close;
+    getOpen: typeof getOpen;
+    position: typeof position;
+};
+
+export default FileChips;
+
+declare global {
+    interface HTMLElementEventMap {
+        'file-chips:change': CustomEvent<FileChipChangeDetail>;
+    }
+
+    interface DocumentEventMap {
+        'file-chips:change': CustomEvent<FileChipChangeDetail>;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ozankurt/file-chips",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Compact file chips with a preview popover and mark-for-removal, framework-free",
     "keywords": [
         "file",
@@ -25,10 +25,12 @@
     "type": "module",
     "main": "dist/file-chips.cjs",
     "module": "dist/esm/file-chips.mjs",
+    "types": "dist/file-chips.d.ts",
     "unpkg": "dist/file-chips.min.js",
     "jsdelivr": "dist/file-chips.min.js",
     "exports": {
         ".": {
+            "types": "./dist/file-chips.d.ts",
             "import": "./dist/esm/file-chips.mjs",
             "require": "./dist/file-chips.cjs",
             "default": "./dist/esm/file-chips.mjs"
@@ -53,14 +55,20 @@
     "scripts": {
         "build": "node ./scripts/build.js",
         "test": "vitest run",
-        "prepublishOnly": "npm test && npm run build"
+        "prepublishOnly": "npm test && npm run typecheck && npm run build",
+        "examples": "vite --config vite.examples.config.js",
+        "screenshots": "node scripts/screenshots.js",
+        "typecheck": "tsc -p tsconfig.types.json"
     },
     "publishConfig": {
         "access": "public"
     },
     "devDependencies": {
+        "@playwright/test": "1.63.0",
         "esbuild": "^0.28.2",
         "happy-dom": "^21.0.3",
+        "typescript": "^5.9.3",
+        "vite": "8.3.4",
         "vitest": "^5.0.5"
     }
 }