@slopmachine/react 0.1.9 → 0.1.12

package/Agents.md

@@ -0,0 +1,34 @@
+# React SDK Conventions
+
+This document outlines the coding conventions and patterns used in the `@slopmachine/react` SDK. Future agents should adhere to these guidelines when making modifications or adding new components.
+
+## Dependencies and Styling
+
+- **Class Merging:** Use `clsx` and `tailwind-merge` to construct and merge Tailwind CSS classes. A utility function `cn(...inputs: ClassValue[])` is typically used for this purpose.
+- **Styling Approach:** Components use Tailwind CSS classes for styling. However, to ensure components remain robust even if the consumer's environment doesn't perfectly process all Tailwind classes, always include equivalent inline `style` properties as a fallback.
+- **CSS Variables:** Use standard CSS variables for theme-related colors (e.g., `var(--muted, #f3f4f6)`).
+- **Custom Animations/Styles:** If complex animations or specific scoped styles are needed that go beyond Tailwind utility classes, inject them using a scoped `<style>` block within the component.
+- **Core Logic:** Import shared logic, utilities, and base types from `@slopmachine/core`.
+
+## Component Structure
+
+- **Functional Components:** Define components as Functional Components (e.g., `React.FC<Props>`).
+- **Prop Forwarding:** Spread the remaining props (`...props`) onto the primary underlying DOM element to allow consumers to pass standard HTML attributes (like `aria-` attributes, data attributes, etc.).
+
+## Prop Typing
+
+- **Interfaces:** Define an explicit `Props` interface for each component.
+- **Extending Standard Attributes:** Extend the appropriate React HTML attributes interface (e.g., `React.ImgHTMLAttributes<HTMLImageElement>`).
+- **Overriding Attributes:** Use `Omit` to exclude standard attributes that are managed internally by the component or replaced by custom SDK options (e.g., `Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "alt">`).
+- **Shared Types:** Extend or incorporate types from `@slopmachine/core` (like `SlopImageOptions`).
+
+## IntelliSense and Documentation
+
+- **JSDoc Comments:** Always include descriptive JSDoc comments for components and their props to provide rich IntelliSense in IDEs.
+- **Component Documentation:** Component JSDoc blocks should describe what the component does and include a clear `@example` block demonstrating usage, and optionally a `@version` tag if applicable.
+- **Prop Documentation:** Every custom prop in a component's interface should have a JSDoc comment explaining its purpose, default behavior, and any edge cases. This is crucial for developer experience when consuming the SDK.
+
+## Exporting Patterns
+
+- **Named Exports:** Use named exports for components and interfaces (e.g., `export const ComponentName = ...`). Avoid default exports.
+- **Entry Point:** Ensure components and their prop types are exported from the package's main entry point if they are meant for public consumption.

package/README.md

@@ -14,7 +14,7 @@ pnpm add @slopmachine/react
 
 ## Demo
 
-https://slopmachine-dev.github.io/slopmachine-sdk/
+https://slopmachine-dev.github.io/slopmachine-sdk/demo-react/
 
 ## Usage
 

package/dist/index.d.mts

@@ -1,8 +1,68 @@
 import React from 'react';
-import { SlopImageOptions } from '@slopmachine/core';
+import { SlopImageOptions, ImageAspectRatio, SlopVideoOptions, VideoAspectRatio } from '@slopmachine/core';
+export { ImageAspectRatio, SlopImageOptions, SlopVideoOptions, VideoAspectRatio } from '@slopmachine/core';
 
-interface SlopImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "alt">, SlopImageOptions {
+interface SlopImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "alt">, Omit<SlopImageOptions, "aspectRatio"> {
+    /**
+     * The aspect ratio of the generated image. Defaults to "1:1".
+     */
+    aspectRatio?: ImageAspectRatio;
+    /**
+     * Custom React node to display while the image is loading.
+     * If not provided, a default spinner and shimmer effect will be shown.
+     */
+    loader?: React.ReactNode;
 }
+/**
+ * Renders an image generated by Slop Machine.
+ *
+ * This component automatically constructs the correct URL for the Slop Machine API,
+ * displays a loading skeleton or custom loader while fetching, and handles errors.
+ *
+ * @example
+ * ```tsx
+ * <SlopImage
+ *   bucketId="my-bucket"
+ *   resultId="some-result"
+ *   aspectRatio="16:9"
+ *   className="rounded-lg"
+ * />
+ * ```
+ *
+ * @version 0.1.12
+ */
 declare const SlopImage: React.FC<SlopImageProps>;
 
-export { SlopImage };
+interface SlopVideoProps extends Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "src">, Omit<SlopVideoOptions, "aspectRatio"> {
+    /**
+     * The aspect ratio of the generated video. Defaults to "16:9".
+     */
+    aspectRatio?: VideoAspectRatio;
+    /**
+     * Custom React node to display while the video is loading.
+     * If not provided, a default spinner and shimmer effect will be shown.
+     */
+    loader?: React.ReactNode;
+}
+/**
+ * Renders a video generated by Slop Machine.
+ *
+ * This component automatically constructs the correct URL for the Slop Machine API,
+ * displays a loading skeleton or custom loader while fetching, and handles errors.
+ *
+ * @example
+ * ```tsx
+ * <SlopVideo
+ *   bucketId="my-bucket"
+ *   resultId="some-result"
+ *   aspectRatio="16:9"
+ *   className="rounded-lg"
+ *   autoPlay
+ *   loop
+ *   muted
+ * />
+ * ```
+ */
+declare const SlopVideo: React.FC<SlopVideoProps>;
+
+export { SlopImage, type SlopImageProps, SlopVideo, type SlopVideoProps };

package/dist/index.d.ts

@@ -1,8 +1,68 @@
 import React from 'react';
-import { SlopImageOptions } from '@slopmachine/core';
+import { SlopImageOptions, ImageAspectRatio, SlopVideoOptions, VideoAspectRatio } from '@slopmachine/core';
+export { ImageAspectRatio, SlopImageOptions, SlopVideoOptions, VideoAspectRatio } from '@slopmachine/core';
 
-interface SlopImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "alt">, SlopImageOptions {
+interface SlopImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "alt">, Omit<SlopImageOptions, "aspectRatio"> {
+    /**
+     * The aspect ratio of the generated image. Defaults to "1:1".
+     */
+    aspectRatio?: ImageAspectRatio;
+    /**
+     * Custom React node to display while the image is loading.
+     * If not provided, a default spinner and shimmer effect will be shown.
+     */
+    loader?: React.ReactNode;
 }
+/**
+ * Renders an image generated by Slop Machine.
+ *
+ * This component automatically constructs the correct URL for the Slop Machine API,
+ * displays a loading skeleton or custom loader while fetching, and handles errors.
+ *
+ * @example
+ * ```tsx
+ * <SlopImage
+ *   bucketId="my-bucket"
+ *   resultId="some-result"
+ *   aspectRatio="16:9"
+ *   className="rounded-lg"
+ * />
+ * ```
+ *
+ * @version 0.1.12
+ */
 declare const SlopImage: React.FC<SlopImageProps>;
 
-export { SlopImage };
+interface SlopVideoProps extends Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "src">, Omit<SlopVideoOptions, "aspectRatio"> {
+    /**
+     * The aspect ratio of the generated video. Defaults to "16:9".
+     */
+    aspectRatio?: VideoAspectRatio;
+    /**
+     * Custom React node to display while the video is loading.
+     * If not provided, a default spinner and shimmer effect will be shown.
+     */
+    loader?: React.ReactNode;
+}
+/**
+ * Renders a video generated by Slop Machine.
+ *
+ * This component automatically constructs the correct URL for the Slop Machine API,
+ * displays a loading skeleton or custom loader while fetching, and handles errors.
+ *
+ * @example
+ * ```tsx
+ * <SlopVideo
+ *   bucketId="my-bucket"
+ *   resultId="some-result"
+ *   aspectRatio="16:9"
+ *   className="rounded-lg"
+ *   autoPlay
+ *   loop
+ *   muted
+ * />
+ * ```
+ */
+declare const SlopVideo: React.FC<SlopVideoProps>;
+
+export { SlopImage, type SlopImageProps, SlopVideo, type SlopVideoProps };