@siratik/wp-component-library 0.1.1 → 0.1.3

package/components/layout/README.md

@@ -0,0 +1,268 @@
+# Layout Components
+
+A comprehensive set of layout control components for WordPress blocks, providing flexbox-based alignment and positioning controls for both toolbar and inspector contexts.
+
+## Features
+
+- Complete flexbox layout control system
+- Toolbar and inspector panel variations
+- Orientation switching (horizontal/vertical)
+- Justification control (main axis alignment)
+- Alignment control (cross axis alignment)
+- Content alignment (text alignment)
+- Flex wrap control
+- Layout width control (full/constrained)
+- Responsive and accessible UI
+
+## Components
+
+### Toolbar Components
+For use in block toolbars:
+- `AlignmentToolbar` - Cross axis alignment
+- `JustificationToolbar` - Main axis alignment
+- `OrientationToolbar` - Flex direction control
+- `ContentAlignmentToolbar` - Text alignment
+
+### Inspector Components
+For use in inspector panels:
+- `AlignmentSettings` - Cross axis alignment settings
+- `JustificationSettings` - Main axis alignment settings
+- `OrientationSettings` - Flex direction settings
+- `ContentAlignmentSettings` - Text alignment settings
+- `AllowWrapSettings` - Flex wrap toggle
+- `LayoutPanel` - Complete layout panel with all controls
+- `LayoutWidthControl` - Full width vs constrained toggle
+
+## Usage
+
+```jsx
+import { 
+    LayoutPanel,
+    OrientationToolbar,
+    JustificationToolbar,
+    AlignmentToolbar 
+} from '@siratik/wp-component-library/components/layout';
+
+// In block toolbar
+<BlockControls>
+    <OrientationToolbar
+        value={orientation}
+        onChange={setOrientation}
+    />
+    <JustificationToolbar
+        value={justification}
+        onChange={setJustification}
+        orientation={orientation}
+    />
+</BlockControls>
+
+// In inspector controls
+<InspectorControls>
+    <LayoutPanel
+        orientation={orientation}
+        onOrientationChange={setOrientation}
+        justification={justification}
+        onJustificationChange={setJustification}
+        alignment={alignment}
+        onAlignmentChange={setAlignment}
+        allowWrap={allowWrap}
+        onAllowWrapChange={setAllowWrap}
+        showOrientationControl={true}
+        showJustificationControl={true}
+        showAlignmentControl={true}
+        showAllowWrapControl={true}
+    />
+</InspectorControls>
+```
+
+## Layout Panel Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `orientation` | `string` | `"horizontal"` | Flex direction: "horizontal" or "vertical" |
+| `onOrientationChange` | `function` | - | Orientation change handler |
+| `justification` | `string` | `"flex-start"` | Main axis alignment |
+| `onJustificationChange` | `function` | - | Justification change handler |
+| `alignment` | `string` | `"flex-start"` | Cross axis alignment |
+| `onAlignmentChange` | `function` | - | Alignment change handler |
+| `contentAlignment` | `string` | `"left"` | Text alignment within items |
+| `onContentAlignmentChange` | `function` | - | Content alignment change handler |
+| `allowWrap` | `boolean` | `false` | Allow flex items to wrap |
+| `onAllowWrapChange` | `function` | - | Wrap change handler |
+| `showOrientationControl` | `boolean` | `true` | Show orientation control |
+| `showJustificationControl` | `boolean` | `true` | Show justification control |
+| `showAlignmentControl` | `boolean` | `true` | Show alignment control |
+| `showContentAlignmentControl` | `boolean` | `false` | Show content alignment control |
+| `showAllowWrapControl` | `boolean` | `true` | Show wrap control |
+| `group` | `string` | `"styles"` | Inspector control group |
+| `resetAll` | `function` | - | Reset all values handler |
+
+## Individual Control Props
+
+All individual controls follow a similar pattern:
+```jsx
+<ControlName
+    value={currentValue}
+    onChange={handleChange}
+    orientation={orientation}  // For context-aware controls
+/>
+```
+
+## Alignment Values
+
+### Justification (Main Axis)
+- `flex-start` - Start of container
+- `center` - Center of container
+- `flex-end` - End of container
+- `space-between` - Space between items
+
+### Alignment (Cross Axis)
+- `flex-start` - Start of container
+- `center` - Center of container
+- `flex-end` - End of container
+- `stretch` - Stretch to fill container
+
+### Content Alignment (Text)
+- `left` - Left aligned text
+- `center` - Center aligned text
+- `right` - Right aligned text
+
+## CSS Generation
+
+The components are designed to work with CSS classes or inline styles:
+
+```jsx
+// Generate CSS classes
+const layoutClasses = classnames({
+    [`is-orientation-${orientation}`]: orientation,
+    [`is-justified-${justification}`]: justification,
+    [`is-aligned-${alignment}`]: alignment,
+    'is-wrap-allowed': allowWrap
+});
+
+// Or use inline styles
+const layoutStyles = {
+    display: 'flex',
+    flexDirection: orientation === 'vertical' ? 'column' : 'row',
+    justifyContent: justification,
+    alignItems: alignment,
+    flexWrap: allowWrap ? 'wrap' : 'nowrap'
+};
+```
+
+## Examples
+
+### Basic Row Layout
+```jsx
+function RowBlock({ attributes, setAttributes }) {
+    const { orientation = 'horizontal', justification = 'flex-start' } = attributes;
+    
+    return (
+        <>
+            <BlockControls>
+                <JustificationToolbar
+                    value={justification}
+                    onChange={(value) => setAttributes({ justification: value })}
+                    orientation={orientation}
+                />
+            </BlockControls>
+            
+            <div className={`row is-justified-${justification}`}>
+                <InnerBlocks />
+            </div>
+        </>
+    );
+}
+```
+
+### Advanced Grid Layout
+```jsx
+function GridBlock({ attributes, setAttributes }) {
+    return (
+        <InspectorControls>
+            <LayoutPanel
+                {...attributes}
+                onOrientationChange={(orientation) => setAttributes({ orientation })}
+                onJustificationChange={(justification) => setAttributes({ justification })}
+                onAlignmentChange={(alignment) => setAttributes({ alignment })}
+                onAllowWrapChange={(allowWrap) => setAttributes({ allowWrap })}
+                showContentAlignmentControl={true}
+                onContentAlignmentChange={(contentAlignment) => setAttributes({ contentAlignment })}
+            />
+        </InspectorControls>
+    );
+}
+```
+
+### Responsive Column Layout
+```jsx
+function ColumnLayout({ attributes, setAttributes }) {
+    const { orientation, alignment, allowWrap } = attributes;
+    
+    return (
+        <>
+            <InspectorControls>
+                <PanelBody title="Layout">
+                    <OrientationSettings
+                        value={orientation}
+                        onChange={(value) => setAttributes({ orientation: value })}
+                    />
+                    <AlignmentSettings
+                        value={alignment}
+                        onChange={(value) => setAttributes({ alignment: value })}
+                        orientation={orientation}
+                    />
+                    <AllowWrapSettings
+                        value={allowWrap}
+                        onChange={(value) => setAttributes({ allowWrap: value })}
+                    />
+                </PanelBody>
+            </InspectorControls>
+            
+            <div 
+                style={{
+                    display: 'flex',
+                    flexDirection: orientation === 'vertical' ? 'column' : 'row',
+                    alignItems: alignment,
+                    flexWrap: allowWrap ? 'wrap' : 'nowrap'
+                }}
+            >
+                <InnerBlocks />
+            </div>
+        </>
+    );
+}
+```
+
+## Layout Width Control
+
+Control whether content uses full width or is constrained:
+
+```jsx
+<LayoutWidthControl
+    layout={layout}
+    onChange={(newLayout) => setAttributes({ layout: newLayout })}
+/>
+
+// Layout object structure:
+{
+    type: 'constrained' | 'default',
+    contentSize: '840px',  // For constrained layout
+    wideSize: '1200px'     // For wide alignment
+}
+```
+
+## Accessibility
+
+- All controls include proper ARIA labels
+- Keyboard navigation fully supported
+- Visual feedback for current selections
+- Screen reader friendly descriptions
+
+## Notes
+
+- Orientation affects available justification/alignment options
+- Icons rotate appropriately for vertical orientation
+- Controls integrate with WordPress ToolsPanel for consistent UX
+- Styled with Emotion for customizable theming
+- All controls are fully controlled components

package/components/link-tools-panel/README.md

@@ -0,0 +1,49 @@
+# Link Tools Panel
+
+Link settings for a block: a URL (WordPress's link search), "Use post permalink", "Open in new tab" and, opt-in, the link's `rel`.
+WordPress's `LinkControl` is laid out for popovers; here it sits flush and fills the panel's width.
+
+## Usage
+
+```jsx
+import { LinkToolsPanel, LinkToolsPanelItems } from '@siratik/wp-component-library';
+
+// Its own "Link" panel (sidebar or a toolbar popover)
+<LinkToolsPanel
+	link={ link }
+	opensInNewTab={ opensInNewTab }
+	isPermalink={ isPermalink }
+	onChange={ ( changes ) => setAttributes( changes ) }
+	panelId={ `${ clientId }-link` }
+/>
+
+// Inside a panel the block already has
+<ToolsPanel label="Settings">
+	<LinkToolsPanelItems
+		link={ link }
+		opensInNewTab={ opensInNewTab }
+		isPermalink={ isPermalink }
+		onChange={ ( changes ) => setAttributes( changes ) }
+	/>
+</ToolsPanel>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `link` | `string` | `''` | Link URL |
+| `opensInNewTab` | `boolean` | `false` | Whether the link opens in a new tab |
+| `isPermalink` | `boolean` | `false` | Use the current post's permalink instead of `link` |
+| `onChange` | `Function` | - | Called with the changed values, e.g. `{ link }` or `{ opensInNewTab }` |
+| `panelId` | `string` | - | The surrounding panel's `panelId`. Items only register with a panel whose id matches |
+| `isShownByDefault` | `boolean` | `true` | Whether URL and "Open in new tab" show before they have a value |
+| `showPermalink` | `boolean` | `true` | Whether to offer "Use post permalink"; pass `false` for blocks with no such setting |
+| `permalinkHelp` | `string` | generic | Help text for "Use post permalink" |
+| `newTabHelp` | `string` | - | Help text shown while "Open in new tab" is on |
+| `showRel` | `boolean` | `false` | Whether to offer "Link rel"; only for blocks that save and render it |
+| `rel` | `string` | `''` | Link rel, e.g. `nofollow sponsored` |
+
+`LinkToolsPanel` also accepts `label` (panel title, default "Link") and `className`.
+
+`LINK_DEFAULTS` holds the default values (`{ link: '', opensInNewTab: false, isPermalink: false, rel: '' }`). `LinkToolsPanel`'s reset only clears `rel` when `showRel` is on.

package/components/link-tools-panel/index.js

@@ -0,0 +1,198 @@
+/**
+ * Link Tools Panel
+ *
+ * Link settings for a block: a URL (WordPress's link search), "Use post
+ * permalink", "Open in new tab" and, when the block asks for it, the link's
+ * rel (e.g. nofollow).
+ *
+ * - `LinkToolsPanelItems`: the controls as tools panel items, for a block
+ *   that already has a ToolsPanel to put them in.
+ * - `LinkToolsPanel`: the same items in their own "Link" panel.
+ */
+import { __experimentalLinkControl as LinkControl } from "@wordpress/block-editor";
+import {
+	TextControl,
+	ToggleControl,
+	__experimentalToolsPanel as ToolsPanel,
+	__experimentalToolsPanelItem as ToolsPanelItem,
+} from "@wordpress/components";
+import { __ } from "@wordpress/i18n";
+
+import { LinkField } from "./styles";
+
+export const LINK_DEFAULTS = {
+	link: "",
+	opensInNewTab: false,
+	isPermalink: false,
+	rel: "",
+};
+
+/**
+ * Link controls as tools panel items.
+ *
+ * @param {Object}   props
+ * @param {string}   props.link                    Link URL.
+ * @param {boolean}  props.opensInNewTab           Whether the link opens in a new tab.
+ * @param {boolean}  props.isPermalink             Whether the current post's permalink is used.
+ * @param {Function} props.onChange                Called with the changed values, e.g. `{ link }`.
+ * @param {string}   [props.panelId]               The surrounding ToolsPanel's `panelId`, if it has one. Items only register with a panel whose id matches.
+ * @param {boolean}  [props.isShownByDefault=true] Whether URL and "Open in new tab" show before they have a value; when false they are added from the panel menu.
+ * @param {boolean}  [props.showPermalink=true]    Whether to offer "Use post permalink", for blocks that have no such setting.
+ * @param {string}   [props.permalinkHelp]         Help text for "Use post permalink".
+ * @param {string}   [props.newTabHelp]            Help text shown while "Open in new tab" is on.
+ * @param {boolean}  [props.showRel=false]         Whether to offer the link's rel, for blocks that save and render it.
+ * @param {string}   [props.rel]                   Link rel, e.g. "nofollow sponsored".
+ */
+export function LinkToolsPanelItems({
+	link = LINK_DEFAULTS.link,
+	opensInNewTab = LINK_DEFAULTS.opensInNewTab,
+	isPermalink = LINK_DEFAULTS.isPermalink,
+	onChange,
+	panelId,
+	isShownByDefault = true,
+	showPermalink = true,
+	permalinkHelp = __(
+		"Automatically use the current post's permalink as the link.",
+		"wp-component-library",
+	),
+	newTabHelp,
+	showRel = false,
+	rel = LINK_DEFAULTS.rel,
+}) {
+	return (
+		<>
+			{showPermalink && (
+				<ToolsPanelItem
+					panelId={panelId}
+					hasValue={() =>
+						isPermalink !== LINK_DEFAULTS.isPermalink
+					}
+					label={__("Use post permalink", "wp-component-library")}
+					onDeselect={() =>
+						onChange({ isPermalink: LINK_DEFAULTS.isPermalink })
+					}
+					isShownByDefault={false}
+				>
+					<ToggleControl
+						__nextHasNoMarginBottom
+						label={__(
+							"Use post permalink",
+							"wp-component-library",
+						)}
+						checked={isPermalink}
+						onChange={(value) => onChange({ isPermalink: value })}
+						help={permalinkHelp}
+					/>
+				</ToolsPanelItem>
+			)}
+
+			{!isPermalink && (
+				<ToolsPanelItem
+					panelId={panelId}
+					hasValue={() => link !== LINK_DEFAULTS.link}
+					label={__("URL", "wp-component-library")}
+					onDeselect={() => onChange({ link: LINK_DEFAULTS.link })}
+					isShownByDefault={isShownByDefault}
+				>
+					<LinkField>
+						<LinkControl
+							searchInputPlaceholder={__(
+								"Search content or type URL",
+								"wp-component-library",
+							)}
+							value={{ url: link }}
+							onChange={({ url }) => onChange({ link: url })}
+							onRemove={() =>
+								onChange({ link: LINK_DEFAULTS.link })
+							}
+							showInitialSuggestions={true}
+							settings={[]}
+						/>
+					</LinkField>
+				</ToolsPanelItem>
+			)}
+
+			<ToolsPanelItem
+				panelId={panelId}
+				hasValue={() =>
+					opensInNewTab !== LINK_DEFAULTS.opensInNewTab
+				}
+				label={__("Open in new tab", "wp-component-library")}
+				onDeselect={() =>
+					onChange({ opensInNewTab: LINK_DEFAULTS.opensInNewTab })
+				}
+				isShownByDefault={isShownByDefault}
+			>
+				<ToggleControl
+					__nextHasNoMarginBottom
+					label={__("Open in new tab", "wp-component-library")}
+					checked={opensInNewTab}
+					onChange={(value) => onChange({ opensInNewTab: value })}
+					help={opensInNewTab ? newTabHelp : undefined}
+				/>
+			</ToolsPanelItem>
+
+			{showRel && (
+				<ToolsPanelItem
+					panelId={panelId}
+					hasValue={() => !!rel}
+					label={__("Link rel", "wp-component-library")}
+					onDeselect={() => onChange({ rel: LINK_DEFAULTS.rel })}
+					isShownByDefault={false}
+				>
+					<TextControl
+						__next40pxDefaultSize
+						__nextHasNoMarginBottom
+						label={__("Link rel", "wp-component-library")}
+						help={__(
+							"Space-separated values, e.g. nofollow or sponsored.",
+							"wp-component-library",
+						)}
+						value={rel}
+						onChange={(value) => onChange({ rel: value })}
+					/>
+				</ToolsPanelItem>
+			)}
+		</>
+	);
+}
+
+/**
+ * Link controls in their own tools panel.
+ *
+ * Takes the same props as `LinkToolsPanelItems`, plus:
+ *
+ * @param {Object}   props
+ * @param {string}   [props.label]     Panel title. Default "Link".
+ * @param {string}   [props.panelId]   Unique id for the panel.
+ * @param {string}   [props.className] Extra class for the panel.
+ * @param {Function} props.onChange    Called with the changed values.
+ */
+export function LinkToolsPanel({
+	label = __("Link", "wp-component-library"),
+	panelId = "link-tools-panel",
+	className,
+	onChange,
+	...itemProps
+}) {
+	return (
+		<ToolsPanel
+			label={label}
+			panelId={panelId}
+			resetAll={() => {
+				// rel only for blocks that offer it (they have the attribute).
+				const { rel, ...defaults } = LINK_DEFAULTS;
+				onChange(itemProps.showRel ? { ...defaults, rel } : defaults);
+			}}
+			className={className}
+		>
+			<LinkToolsPanelItems
+				{...itemProps}
+				onChange={onChange}
+				panelId={panelId}
+			/>
+		</ToolsPanel>
+	);
+}
+
+export default LinkToolsPanel;

package/components/link-tools-panel/styles.js

@@ -0,0 +1,90 @@
+/**
+ * Emotion styled components for the Link Tools Panel.
+ */
+import styled from "@emotion/styled";
+
+/**
+ * Wraps WordPress's LinkControl inside a tools panel.
+ *
+ * LinkControl is laid out for popovers: a 350px minimum width and 16px
+ * gutters around each of its parts. In a tools panel the panel provides the
+ * gutters, so the field sits flush and fills the panel's width.
+ */
+export const LinkField = styled.div`
+	.block-editor-link-control {
+		min-width: 0;
+		width: 100%;
+	}
+
+	.block-editor-link-control__search-input-wrapper {
+		margin-bottom: 0;
+	}
+
+	.block-editor-link-control__field {
+		margin: 0;
+	}
+
+	.block-editor-url-input {
+		min-width: 0;
+		width: 100%;
+	}
+
+	/* A chosen link: its preview row. */
+	.block-editor-link-control__preview {
+		padding: 0;
+	}
+
+	.block-editor-link-control__search-actions {
+		padding: 8px 0 0;
+	}
+
+	/* Search results: a bordered list under the field, as wide as the panel. */
+	.block-editor-link-control__search-results-wrapper {
+		margin-top: 4px;
+
+		/* Core's scroll fades are positioned for the popover's gutters. */
+		&::before,
+		&::after {
+			display: none;
+		}
+	}
+
+	.block-editor-link-control__search-results {
+		margin: 0;
+		padding: 4px;
+		max-height: 240px;
+		overflow-x: hidden;
+		background: var(--wp-components-color-background, #fff);
+		border: 1px solid var(--wp-components-color-gray-300, #ddd);
+		border-radius: 2px;
+	}
+
+	.block-editor-link-control__search-item.components-button {
+		width: 100%;
+		min-width: 0;
+		height: auto;
+		padding: 6px 8px;
+	}
+
+	.block-editor-link-control__search-item .components-menu-item__item,
+	.block-editor-link-control__search-item .components-menu-item__info-wrapper {
+		min-width: 0;
+	}
+
+	/* One line each for the title and URL, truncated to the panel's width. */
+	.block-editor-link-control__search-item .components-menu-item__info-wrapper > * {
+		display: block;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	/* The type label ("Page", "Attachment") doesn't fit; the icon shows the type. */
+	.block-editor-link-control__search-item .components-menu-item__shortcut {
+		display: none;
+	}
+
+	.block-editor-link-control__help {
+		padding: 0;
+	}
+`;