@siratik/wp-component-library 0.1.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,5 @@
+# License
+
+This software is licensed under the GPL version 3 or later.
+
+See <https://www.gnu.org/licenses/gpl-3.0.html> for the full license text.

package/README.md

@@ -1,4 +1,4 @@
-# WP Component Library
+# Siratik WP Component Library
 
 A comprehensive library of reusable React components, hooks, and utilities for WordPress block development. Built for use with `@wordpress/scripts` and the Gutenberg block editor.
 
@@ -8,6 +8,14 @@ A comprehensive library of reusable React components, hooks, and utilities for W
 npm install @siratik/wp-component-library
 ```
 
+The package ships source (ES modules + JSX), so build it with `@wordpress/scripts` or another
+bundler that transpiles dependencies. There are two entry points:
+
+- `@siratik/wp-component-library`: everything below except the post-editor-only exports.
+- `@siratik/wp-component-library/editor`: `MetaPanel`, `AttributesPanel`, `useAttributes` and the
+  meta-gated editor helpers, which need `@wordpress/editor`. Keeping them separate means screens
+  outside the post editor never load `@wordpress/editor`.
+
 ## Components
 
 ### Icons
@@ -161,8 +169,8 @@ Post query builder controls that compose into a consistent query panel.
 
 | Export | Description |
 |---|---|
-| `AttributesPanel` | Dynamic HTML attribute editor (id, rel, title, etc.) |
-| `useAttributes()` | Hook for managing the attributes array state |
+| `AttributesPanel` | Dynamic HTML attribute editor (id, rel, title, etc.). From `/editor` |
+| `useAttributes()` | Hook for managing the attributes array state. From `/editor` |
 | `SortableSelect` | Token field with drag-to-reorder |
 | `tokensToString()` | Utility — converts token array to comma string |
 | `VariableField` | Text input with `@`-triggered variable autocomplete |
@@ -198,6 +206,8 @@ import { Repeater } from "@siratik/wp-component-library";
 
 ### Meta
 
+Import these from `@siratik/wp-component-library/editor`.
+
 | Export | Description |
 |---|---|
 | `MetaPanel` | Document sidebar modal for editing post meta |
@@ -236,11 +246,19 @@ Customisable appender buttons for inner blocks.
 
 ---
 
+### StylePicker
+
+| Export | Description |
+|---|---|
+| `StylePicker` | One of a few options, shown like core's block Styles panel (for a style-like attribute) |
+
+---
+
 ### Button
 
 | Export | Description |
 |---|---|
-| `ButtonFrontend` | Minimal frontend button — safe to use outside the editor |
+| `ButtonFrontend` | Minimal frontend button — safe to use outside the editor. `style` (Fill / Outline) and `variant` (Primary, Secondary, Tertiary, Text Link) |
 
 ---
 
@@ -253,6 +271,26 @@ Customisable appender buttons for inner blocks.
 
 Several patterns and ideas in this library were inspired by the excellent open-source work from **[10up](https://github.com/10up)**, particularly [`@10up/block-components`](https://github.com/10up/block-components). Their `registerBlockExtension` API and icon picker concepts were especially influential in shaping the equivalent features here. We're grateful for the work they've done for the WordPress developer community.
 
+## License
+
+GPL-3.0-or-later — see `LICENSE`.
+
 ## Disclaimer
 
-This library is provided "as is" without warranty of any kind. Always test components in your specific environment before deploying to production.
+This software is provided "as is", without warranty of any kind, express or
+implied, including the warranties of merchantability and fitness for a
+particular purpose. To the extent permitted by applicable law, the authors and
+copyright holders, together with their parent, subsidiary, and affiliated
+companies and contributors, are not liable for any direct, indirect,
+incidental, or consequential damages arising from its use or inability to use
+it, including loss of data, revenue, or site availability.
+
+The software does not guarantee that your site is secure, ranks in search
+results, or complies with privacy or other laws; that remains the site owner's
+responsibility. AI-generated content can be inaccurate and should be reviewed
+before publishing. Third-party services the software connects to are governed
+by their own terms.
+
+Keep a current backup and test changes on a staging site before applying them
+to a live site. See sections 15 and 16 of the GNU General Public License,
+version 3, for the full terms.

package/components/attachment-image/README.md

@@ -0,0 +1,118 @@
+# AttachmentImage Component
+
+A flexible image display component that fetches and renders WordPress media attachments with responsive features and caption support. This component serves as a JavaScript companion to WordPress's `wp_get_attachment()` function.
+
+## Features
+
+- WordPress media integration with automatic attachment fetching
+- Responsive image handling with srcSet support
+- Multiple WordPress image sizes support
+- Flexible caption display (media caption or custom)
+- BEM-style CSS class generation
+- Graceful handling of missing images
+- Figure element wrapping with optional disable
+
+## Usage
+
+```jsx
+import { AttachmentImage } from '@siratik/wp-component-library/components/attachment-image';
+
+// Basic usage
+<AttachmentImage 
+    imageId={123} 
+    size="large"
+/>
+
+// With caption and custom styling
+<AttachmentImage
+    imageId={456}
+    size="full"
+    showCaption={true}
+    className="hero-image"
+    wrapClass="hero-figure"
+    aspectRatio="16/9"
+    maxWidth="1200px"
+/>
+
+// Without figure wrapper
+<AttachmentImage
+    imageId={789}
+    includeFigure={false}
+    customAlt="Custom alt text"
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `imageId` | `number` | Required | WordPress media attachment ID |
+| `className` | `string` | `"image"` | CSS class for the img element |
+| `customAlt` | `string` | - | Override default alt text from media library |
+| `showCaption` | `boolean` | `false` | Display image caption below image |
+| `wrapClass` | `string` | - | CSS class for the wrapper figure element |
+| `includeFigure` | `boolean` | `true` | Wrap image in figure element |
+| `size` | `string` | `"full"` | WordPress image size (thumbnail, medium, large, full, or custom) |
+| `maxWidth` | `string` | `"100px"` | Maximum width for responsive sizing |
+| `aspectRatio` | `string` | `"4/3"` | CSS aspect ratio value |
+| `caption` | `string` | - | Custom caption text (overrides media caption) |
+
+## WordPress Image Sizes
+
+The component supports all registered WordPress image sizes:
+- `thumbnail` - Small square crop
+- `medium` - Medium size
+- `large` - Large size
+- `full` - Original uploaded size
+- Custom sizes registered in your theme
+
+## CSS Classes
+
+The component generates BEM-style classes:
+- Image: `{className}` (default: "image")
+- Figure wrapper: `{wrapClass}` or `{className}__wrap`
+- Caption: `{className}__caption`
+
+## Examples
+
+### Hero Image with Caption
+```jsx
+<AttachmentImage
+    imageId={heroImageId}
+    size="full"
+    showCaption={true}
+    className="hero"
+    aspectRatio="21/9"
+    maxWidth="100vw"
+/>
+```
+
+### Gallery Thumbnail
+```jsx
+<AttachmentImage
+    imageId={thumbnailId}
+    size="thumbnail"
+    className="gallery-item"
+    includeFigure={false}
+/>
+```
+
+### Responsive Card Image
+```jsx
+<AttachmentImage
+    imageId={cardImageId}
+    size="medium"
+    className="card-image"
+    aspectRatio="1/1"
+    maxWidth="400px"
+    customAlt="Product preview"
+/>
+```
+
+## Notes
+
+- The component uses WordPress's `core` data store to fetch media information
+- If the image is not found, the component returns `null` gracefully
+- Alt text priority: `customAlt` prop > media library alt > empty string
+- The component automatically generates responsive srcSet for better performance
+- Additional props can be passed through to the img element

package/components/attachment-image/index.js

@@ -0,0 +1,105 @@
+import { useSelect } from "@wordpress/data";
+
+/**
+ * AttachmentImage
+ *
+ * @param {object} props
+ * @param {number} props.id The ID of the image to display.
+ * @param {string} props.className Optional. The class to add to the image.
+ * @param {string} props.customAlt Optional. The custom alt text to use for the image.
+ * @param {boolean} props.showCaption Optional. Whether to show the caption.
+ * @param {string} props.wrapClass Optional. The class to add to the figure.
+ * @param {boolean} props.includeFigure Optional. Whether to include the figure.
+ * @param {string} props.size Optional. The size of the image.
+ * @param {string} props.maxWidth Optional. The maximum width of the image.
+ * @param {string} [props.objectFit] Optional CSS object-fit (e.g. "cover").
+ * @returns {*} React JSX
+ */
+function AttachmentImage({
+    imageId,
+    className = "image",
+    customAlt = null,
+    showCaption = false,
+    wrapClass = null,
+    includeFigure = true,
+    size = "full",
+    maxWidth = "100px",
+    aspectRatio = "4/3",
+    objectFit = null,
+    caption = null,
+    ...overrideProps
+}) {
+    const { image } = useSelect((select) => ({
+        image: select("core").getEntityRecord("postType", "attachment", imageId),
+    }));
+
+    if (!imageId || imageId === 0 || !image) { return null; }
+
+    const appendToFirstClass = (classString, appendix) => {
+        const classes = classString.split(" ");
+        if (classes.length > 0) {
+            classes[0] = `${classes[0]}${appendix}`;
+        }
+        return classes.join(" ");
+    };
+
+    const imageAttributes = () => {
+        const attributes = {
+            className: appendToFirstClass(className, "__img"),
+            src: image.source_url,
+            alt: customAlt || image.alt_text,
+            width: image.media_details.width,
+            height: image.media_details.height,
+            sizes: `(max-width: ${maxWidth}) 100vw, ${maxWidth}`,
+            style: {
+                aspectRatio,
+                ...(objectFit ? { objectFit } : {}),
+            },
+        };
+
+        if (
+            image.media_details &&
+            image.media_details.sizes &&
+            image.media_details.sizes[size]
+        ) {
+            attributes.src = image.media_details.sizes[size].source_url;
+            attributes.srcSet = image.media_details.sizes[size].source_url;
+            attributes.width = image.media_details.sizes[size].width;
+            attributes.height = image.media_details.sizes[size].height;
+        }
+
+        return { ...attributes, ...overrideProps };
+    };
+
+    // eslint-disable-next-line jsx-a11y/alt-text -- alt comes from imageAttributes().
+    const imgElement = <img {...imageAttributes()} />;
+    const captionElement =
+        showCaption && caption ? (
+            <figcaption className={appendToFirstClass(className, "__caption")}>
+                {caption}
+            </figcaption>
+        ) : null;
+
+    if (includeFigure) {
+        const figureClass = wrapClass
+            ? `${appendToFirstClass(className, "__figure")} ${wrapClass}`
+            : appendToFirstClass(className, "__figure");
+
+        return (
+            <figure className={figureClass}>
+                {imgElement}
+                {captionElement}
+            </figure>
+        );
+    }
+
+    return (
+        <>
+            {imgElement}
+            {captionElement}
+        </>
+    );
+}
+
+// Export Component
+export { AttachmentImage };

package/components/attributes-panel/README.md

@@ -0,0 +1,92 @@
+# AttributesPanel Component
+
+A ToolsPanel-based component that provides attribute management for blocks in the Site Editor, with ComboboxControl for selecting from available meta fields and HTML attributes.
+
+## Features
+
+- Uses WordPress ToolsPanel for consistent UI
+- ComboboxControl populated with:
+  - Common HTML attributes (id, class, style, etc.)
+  - ARIA attributes
+  - Data attributes
+  - Available post meta fields
+- Dynamic attribute addition/removal
+- Per-attribute reset functionality
+- Global reset all attributes
+
+## Usage
+
+```jsx
+import { AttributesPanel, useAttributes } from '@siratik/wp-component-library/components/attributes-panel';
+
+function MyComponent() {
+	const { attributes, setAttributes } = useAttributes([
+		{ id: 'id', label: 'ID', value: '' },
+		{ id: 'alt', label: 'Alt Text', value: '' }
+	]);
+
+	return (
+		<AttributesPanel
+			attributes={attributes}
+			onChange={setAttributes}
+			panelId="my-attributes-panel"
+		/>
+	);
+}
+```
+
+## Props
+
+### AttributesPanel
+
+- `attributes` (Array): Array of attribute objects with `id`, `label`, and `value` properties
+- `onChange` (Function): Callback when attributes change, receives updated attributes array
+- `panelId` (string): Unique ID for the tools panel (default: 'attributes-panel')
+
+### useAttributes Hook
+
+Returns an object with:
+- `attributes`: Current attributes array
+- `setAttributes`: Set entire attributes array
+- `updateAttribute(id, value)`: Update a specific attribute
+- `addAttribute(label, value)`: Add new attribute
+- `removeAttribute(id)`: Remove attribute by id
+- `resetAttributes()`: Reset all attribute values
+- `getAttributeValue(id)`: Get value for specific attribute
+
+## Site Editor Integration
+
+The component is integrated into the Site Editor for specific core blocks (image, paragraph, heading, button) via the block extension system. It automatically:
+
+1. Detects when in Site Editor context
+2. Shows appropriate default attributes for each block type
+3. Populates ComboboxControl with available meta fields
+4. Saves attributes to block's customAttributes array
+
+## Available Attribute Options
+
+The ComboboxControl is populated with:
+
+### HTML Attributes
+- id, class, style, title, alt, rel, target, href, src
+
+### Data Attributes
+- data-id, data-type, data-value
+
+### ARIA Attributes
+- aria-label, aria-describedby, aria-hidden
+
+### Meta Fields
+- All available post meta fields (prefixed with "Meta:")
+- Common WordPress meta fields like _thumbnail_id, _wp_page_template
+
+Users can also type custom attribute names not in the list.
+
+## Security
+
+The panel refuses event handler attribute names (anything starting with `on`, such as `onclick`) and `javascript:`, `vbscript:` and `data:` URLs in URL attributes (`href`, `src`, `srcset`, `action`, `formaction`, `poster`, `xlink:href`). This is only a guard in the editor UI. Saved attributes can still be changed by other means, so the code that outputs them must:
+
+- allowlist the attribute names it renders, and
+- escape every value on output (`esc_attr()`, and `esc_url()` for URL attributes).
+
+`isUnsafeAttributeName()` and `isUnsafeAttributeValue()` are exported from this module so consumers can reuse the same checks.