@siratik/wp-component-library 0.1.1 → 0.1.2

package/components/media/README.md

@@ -0,0 +1,288 @@
+# Media Components
+
+A comprehensive set of media upload and management components for WordPress blocks, providing different UI patterns for various contexts within the block editor.
+
+## Components
+
+### ToolbarMediaUpload
+Media upload button for block toolbars with customizable icons and labels.
+
+### EditorMediaUpload
+Flexible media upload component for the main editor canvas with image preview support.
+
+### InspectorMediaUpload
+Media upload control for inspector panels with integrated preview and management.
+
+### SettingsMediaUpload
+Advanced media upload for settings panels with focal point control and additional options.
+
+### ImageControls
+Comprehensive image control panel with aspect ratio, object fit, and focal point settings.
+
+## Usage
+
+```jsx
+import { 
+    ToolbarMediaUpload,
+    EditorMediaUpload,
+    InspectorMediaUpload,
+    SettingsMediaUpload,
+    ImageControls
+} from '@siratik/wp-component-library/components/media';
+
+// Toolbar upload
+<BlockControls>
+    <ToolbarMediaUpload
+        buttonTitle="Select Image"
+        onSelect={handleImageSelect}
+        allowedTypes={['image']}
+        value={imageId}
+    />
+</BlockControls>
+
+// Editor canvas upload
+<EditorMediaUpload
+    buttonTitle="Choose Background"
+    onSelect={handleImageSelect}
+    imageUrl={backgroundUrl}
+    imageAlt={backgroundAlt}
+/>
+
+// Inspector panel upload
+<InspectorControls>
+    <InspectorMediaUpload
+        buttonTitle="Upload Logo"
+        onSelect={handleLogoSelect}
+        onRemove={handleLogoRemove}
+        imageId={logoId}
+        imageUrl={logoUrl}
+    />
+</InspectorControls>
+
+// Advanced settings upload
+<SettingsMediaUpload
+    label="Hero Image"
+    onSelect={handleHeroSelect}
+    onRemove={handleHeroRemove}
+    value={heroImage}
+    focalPoint={focalPoint}
+    onFocalPointChange={setFocalPoint}
+/>
+```
+
+## Common Props
+
+### Core Props (All Components)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onSelect` | `function` | Required | Media selection handler |
+| `allowedTypes` | `array` | `['image']` | Allowed media types |
+| `buttonTitle` | `string` | Varies | Button label text |
+
+### ToolbarMediaUpload Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | - | Selected media ID |
+| `buttonIcon` | `element` | `image` | Toolbar button icon |
+| `buttonLabel` | `string` | - | Accessibility label |
+| `multiple` | `boolean` | `false` | Allow multiple selection |
+| `gallery` | `boolean` | `false` | Gallery mode |
+
+### EditorMediaUpload Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `imageUrl` | `string` | - | Current image URL for preview |
+| `imageAlt` | `string` | - | Image alt text |
+| `imageId` | `number` | - | Current image ID |
+| `onRemove` | `function` | - | Image removal handler |
+| `className` | `string` | - | Additional CSS classes |
+
+### InspectorMediaUpload Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `imageId` | `number` | - | Current image ID |
+| `imageUrl` | `string` | - | Current image URL |
+| `onRemove` | `function` | - | Image removal handler |
+| `label` | `string` | - | Control label |
+| `help` | `string` | - | Help text |
+
+### SettingsMediaUpload Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | `"Image"` | Control label |
+| `value` | `object` | - | Image data object |
+| `onRemove` | `function` | - | Image removal handler |
+| `focalPoint` | `object` | - | Focal point coordinates |
+| `onFocalPointChange` | `function` | - | Focal point change handler |
+| `help` | `string` | - | Help text |
+
+## ImageControls Component
+
+Advanced image settings panel with comprehensive controls:
+
+```jsx
+<ImageControls
+    imageId={imageId}
+    imageUrl={imageUrl}
+    onRemove={handleRemove}
+    aspectRatio={aspectRatio}
+    onAspectRatioChange={setAspectRatio}
+    objectFit={objectFit}
+    onObjectFitChange={setObjectFit}
+    focalPoint={focalPoint}
+    onFocalPointChange={setFocalPoint}
+    imagePosition={imagePosition}
+    onImagePositionChange={setImagePosition}
+/>
+```
+
+### ImageControls Props
+| Prop | Type | Description |
+|------|------|-------------|
+| `imageId` | `number` | Current image ID |
+| `imageUrl` | `string` | Current image URL |
+| `onRemove` | `function` | Image removal handler |
+| `aspectRatio` | `string` | Aspect ratio value |
+| `onAspectRatioChange` | `function` | Aspect ratio change handler |
+| `objectFit` | `string` | Object fit value (cover, contain, etc.) |
+| `onObjectFitChange` | `function` | Object fit change handler |
+| `focalPoint` | `object` | Focal point {x, y} coordinates |
+| `onFocalPointChange` | `function` | Focal point change handler |
+| `imagePosition` | `string` | CSS background position |
+| `onImagePositionChange` | `function` | Position change handler |
+
+## Aspect Ratios
+
+The library includes predefined aspect ratios via `ASPECT_RATIOS`:
+
+```jsx
+import { ASPECT_RATIOS } from '@siratik/wp-component-library/components/media/utils/aspect-ratios';
+
+// Available ratios:
+{
+    'original': 'Original',
+    '1-1': 'Square (1:1)',
+    '4-3': 'Standard (4:3)',
+    '16-9': 'Widescreen (16:9)',
+    '21-9': 'Ultrawide (21:9)',
+    '3-2': 'Classic (3:2)',
+    '5-4': 'Large Format (5:4)',
+    '9-16': 'Portrait (9:16)'
+}
+```
+
+## Examples
+
+### Hero Section with Background
+```jsx
+function HeroSection({ attributes, setAttributes }) {
+    const { backgroundImage, focalPoint } = attributes;
+    
+    return (
+        <>
+            <InspectorControls>
+                <PanelBody title="Background">
+                    <SettingsMediaUpload
+                        label="Background Image"
+                        value={backgroundImage}
+                        onSelect={(media) => setAttributes({ 
+                            backgroundImage: {
+                                id: media.id,
+                                url: media.url,
+                                alt: media.alt
+                            }
+                        })}
+                        onRemove={() => setAttributes({ backgroundImage: null })}
+                        focalPoint={focalPoint}
+                        onFocalPointChange={(point) => setAttributes({ focalPoint: point })}
+                    />
+                </PanelBody>
+            </InspectorControls>
+            
+            <div 
+                className="hero"
+                style={{
+                    backgroundImage: `url(${backgroundImage?.url})`,
+                    backgroundPosition: `${focalPoint?.x * 100}% ${focalPoint?.y * 100}%`
+                }}
+            >
+                {/* Hero content */}
+            </div>
+        </>
+    );
+}
+```
+
+### Gallery Block
+```jsx
+function GalleryBlock({ attributes, setAttributes }) {
+    const { images } = attributes;
+    
+    return (
+        <BlockControls>
+            <ToolbarMediaUpload
+                buttonTitle="Add Images"
+                buttonIcon={gallery}
+                onSelect={(media) => {
+                    const newImages = media.map(item => ({
+                        id: item.id,
+                        url: item.url,
+                        alt: item.alt
+                    }));
+                    setAttributes({ images: [...images, ...newImages] });
+                }}
+                multiple={true}
+                gallery={true}
+                allowedTypes={['image']}
+            />
+        </BlockControls>
+    );
+}
+```
+
+### Card with Featured Image
+```jsx
+function Card({ attributes, setAttributes }) {
+    const { featuredImage, aspectRatio, objectFit } = attributes;
+    
+    return (
+        <InspectorControls>
+            <PanelBody title="Featured Image">
+                <ImageControls
+                    imageId={featuredImage?.id}
+                    imageUrl={featuredImage?.url}
+                    onRemove={() => setAttributes({ featuredImage: null })}
+                    aspectRatio={aspectRatio}
+                    onAspectRatioChange={(ratio) => setAttributes({ aspectRatio: ratio })}
+                    objectFit={objectFit}
+                    onObjectFitChange={(fit) => setAttributes({ objectFit: fit })}
+                />
+            </PanelBody>
+        </InspectorControls>
+    );
+}
+```
+
+## Media Selection Handler
+
+Standard media selection handler pattern:
+```jsx
+const handleMediaSelect = (media) => {
+    setAttributes({
+        imageId: media.id,
+        imageUrl: media.url,
+        imageAlt: media.alt,
+        imageWidth: media.width,
+        imageHeight: media.height
+    });
+};
+```
+
+## Notes
+
+- All components integrate with WordPress MediaUpload
+- Components handle both selection and removal of media
+- Focal point control uses WordPress FocalPointPicker
+- Image preview automatically displayed when URL provided
+- Components styled to match WordPress admin UI
+- Supports all WordPress media types via allowedTypes prop

package/components/media/SettingsMediaUpload.js

@@ -0,0 +1,187 @@
+/**
+ * Settings Media Upload Component
+ * Designed for admin settings contexts (not block editor)
+ */
+import { MediaUpload, MediaUploadCheck } from "@wordpress/media-utils";
+import { Button, Flex, Placeholder } from "@wordpress/components";
+import { useSelect } from "@wordpress/data";
+import { __ } from "@wordpress/i18n";
+import styled from '@emotion/styled';
+
+const ALLOWED_MEDIA_TYPES = ["image"];
+
+// Styled components
+const StyledSettingsMediaUpload = styled.div`
+    &__header {
+        margin-bottom: 12px;
+    }
+`;
+
+const StyledLabel = styled.h4`
+    margin: 0 0 4px 0;
+    font-size: 13px;
+    font-weight: 600;
+    color: #1e1e1e;
+`;
+
+const StyledHelp = styled.p`
+    margin: 0;
+    font-size: 13px;
+    color: #757575;
+    line-height: 1.4;
+`;
+
+const StyledPreview = styled.div`
+    margin-bottom: 12px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    overflow: hidden;
+    background: #f9f9f9;
+`;
+
+const StyledImage = styled.img`
+    max-width: 100%;
+    height: auto;
+    display: block;
+    max-height: 200px;
+    object-fit: cover;
+`;
+
+const StyledPlaceholder = styled(Placeholder)`
+    min-height: 120px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    
+    .components-placeholder__label {
+        font-size: 13px;
+        color: #757575;
+    }
+    
+    .components-placeholder__icon {
+        margin-bottom: 8px;
+        opacity: 0.3;
+    }
+`;
+
+const StyledButtons = styled.div`
+    .components-flex {
+        align-items: center;
+    }
+
+    .components-button {
+        min-width: 100px;
+    }
+`;
+
+/**
+ * Settings Media Upload
+ * 
+ * @param {object} props
+ * @param {number|null} props.imageId - The ID of the selected image
+ * @param {Function} props.onSelect - Callback when image is selected
+ * @param {Function} props.onRemove - Callback when image is removed
+ * @param {string} props.label - Label for the control
+ * @param {string} props.help - Help text for the control
+ * @param {string} props.buttonTitle - Custom button text
+ * @param {boolean} props.showImagePlaceholder - Whether to show image preview
+ * @param {string} props.size - Image size for preview (default: 'medium')
+ * @returns {JSX.Element}
+ */
+function SettingsMediaUpload({
+    imageId,
+    onSelect,
+    onRemove,
+    label = null,
+    help = null,
+    buttonTitle = null,
+    showImagePlaceholder = true,
+}) {
+    // Get image data for preview
+    const imageData = useSelect(
+        (select) => {
+            if (!imageId) { return null; }
+            return select("core").getEntityRecord("postType", "attachment", imageId);
+        },
+        [imageId]
+    );
+
+    const hasImage = !!imageId;
+
+    return (
+        <StyledSettingsMediaUpload>
+            {/* Label and Help */}
+            {(label || help) && (
+                <div className="settings-media-upload__header">
+                    {label && (
+                        <StyledLabel>
+                            {label}
+                        </StyledLabel>
+                    )}
+                    {help && (
+                        <StyledHelp>
+                            {help}
+                        </StyledHelp>
+                    )}
+                </div>
+            )}
+
+            {/* Image Preview or Placeholder */}
+            {showImagePlaceholder && (
+                <StyledPreview>
+                    {hasImage && imageData ? (
+                        <StyledImage
+                            src={imageData.source_url}
+                            alt={imageData.alt_text || "Selected image"}
+                        />
+                    ) : (
+                        <StyledPlaceholder
+                            icon="format-image"
+                            label={__("No image selected", "wp-component-library")}
+                        />
+                    )}
+                </StyledPreview>
+            )}
+
+            {/* Buttons */}
+            <StyledButtons>
+                <MediaUploadCheck>
+                    <Flex gap={2}>
+                        <MediaUpload
+                            onSelect={onSelect}
+                            allowedTypes={ALLOWED_MEDIA_TYPES}
+                            value={imageId}
+                            render={({ open }) => (
+                                <Button
+                                    variant="secondary"
+                                    onClick={open}
+                                    size="default"
+                                >
+                                    {buttonTitle || 
+                                        (hasImage 
+                                            ? __("Change Image", "wp-component-library")
+                                            : __("Upload Image", "wp-component-library")
+                                        )
+                                    }
+                                </Button>
+                            )}
+                        />
+                        
+                        {hasImage && (
+                            <Button
+                                variant="secondary"
+                                isDestructive={true}
+                                onClick={onRemove}
+                                size="default"
+                            >
+                                {__("Remove Image", "wp-component-library")}
+                            </Button>
+                        )}
+                    </Flex>
+                </MediaUploadCheck>
+            </StyledButtons>
+        </StyledSettingsMediaUpload>
+    );
+}
+
+export { SettingsMediaUpload };

package/components/media/editor-media-upload.js

@@ -0,0 +1,65 @@
+/**
+ * Editor Media Upload Component
+ */
+import { MediaUpload, MediaUploadCheck } from "@wordpress/block-editor";
+import { Button, Placeholder } from "@wordpress/components";
+import { upload } from "@wordpress/icons";
+
+const ALLOWED_MEDIA_TYPES = ["image"];
+
+/**
+ * Editor Media Upload
+ *
+ * @param {object} props
+ * @returns {JSX.Element}
+ */
+function EditorMediaUpload({
+    mediaIDs,
+    onSelect,
+    gallery,
+    multiple,
+    buttonTitle,
+    style,
+}) {
+    // Handle both ID and object formats for mediaIDs
+    const getMediaId = (mediaData) => {
+        if (!mediaData) { return null; }
+        if (typeof mediaData === "number") { return mediaData; }
+        if (typeof mediaData === "object" && mediaData.id) { return mediaData.id; }
+        return null;
+    };
+
+    const mediaId = getMediaId(mediaIDs);
+
+    return (
+        <Placeholder
+            style={style}
+            withIllustration={true}
+            className="placeholder-image placeholder-image--built"
+        >
+            <MediaUploadCheck>
+                <MediaUpload
+                    onSelect={onSelect}
+                    allowedTypes={ALLOWED_MEDIA_TYPES}
+                    value={mediaId}
+                    render={({ open }) => (
+                        <Button
+                            icon={upload}
+                            variant="primary"
+                            label="Upload or Select Image(s)"
+                            showTooltip
+                            tooltipPosition="top center"
+                            onClick={open}
+                        >
+                            {buttonTitle}
+                        </Button>
+                    )}
+                    gallery={gallery}
+                    multiple={multiple}
+                />
+            </MediaUploadCheck>
+        </Placeholder>
+    );
+}
+
+export { EditorMediaUpload };