@youasked/react 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aden Teo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @youasked/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Feature requests your users can vote on, built into your React app. People ask and vote without leaving the app, you hear about it on your phone, and everyone who asked is told when it ships.
+
+Site and live demo: https://youasked.adenteo.workers.dev
+
+## Set up
+
+The quickest way is to run this in your project root. It creates the app, writes the keys and adds the components you pick:
+
+```sh
+npx youasked init
+```
+
+Or by hand:
+
+```sh
+npm i @youasked/react
+```
+
+```tsx
+"use client";
+import { YouAsked } from "@youasked/react";
+
+export function FeatureRequests({ children }: { children: React.ReactNode }) {
+  return <YouAsked appKey={process.env.NEXT_PUBLIC_YOUASKED_KEY!}>{children}</YouAsked>;
+}
+```
+
+`trigger="floating"` (the default) adds a chat bubble in the corner. Use `trigger="none"` and the entry points below if you'd rather place it yourself.
+
+## Entry points
+
+All of them open the same sheet, in your colours, font and dark mode.
+
+| Component | Use it for |
+|---|---|
+| `<AskBar />` | A chat-style input on a home screen |
+| `<FeatureCard />` | Top requests with vote buttons on a dashboard |
+| `<RequestButton variant="icon" />` | A round header button, with a badge when something ships |
+| `<RequestButton variant="row" />` | A settings row |
+| `<RequestButton variant="pill" />` | A tinted pill anywhere |
+| `<AskAbout topic="charts" />` | A quiet prompt next to a feature |
+| `<AskForIt query={search} />` | An empty search result that offers to ask for it |
+| `<FeatureBoard />` | Everything inline, for a `/feedback` page |
+| `useYouAsked().open({ view: "new", draft: "Export to Excel" })` | Any button, such as a locked feature |
+
+## Signed-in users
+
+Without this, visitors are anonymous (one ID per device). With sign-in, sign the user ID on your server so nobody can vote as someone else:
+
+```ts
+// app/api/youasked/identity/route.ts
+import { signUser } from "@youasked/react/server";
+
+export async function GET() {
+  const user = await getCurrentUser(); // your auth
+  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
+  return Response.json({ userId: user.id, signature: await signUser(process.env.YOUASKED_SECRET_KEY!, user.id) });
+}
+```
+
+Then pass `user={{ id: userId }} signature={signature} ready={loaded}` to `<YouAsked>`. Never put `YOUASKED_SECRET_KEY` in client code.
+
+## Theming
+
+It reads shadcn tokens (`--primary`, `--background`, `--radius` and so on) on its own. Otherwise pass `appearance`:
+
+```tsx
+<YouAsked appKey="ya_pub_…" appearance={{ accent: "#5b3df5", radius: 16, fontFamily: "inherit" }} />
+```
+
+Dark mode follows the page's `.dark` class or `data-theme`.
+
+## Shipping
+
+Connect Telegram, Slack, Discord or GitHub from the dashboard. A commit with `closes YA-12` on your default branch marks request YA-12 shipped and tells everyone who asked. To let your coding agent read and ship requests, add the MCP server:
+
+```sh
+claude mcp add youasked -e YOUASKED_SECRET_KEY=ya_sec_… -- npx -y @youasked/mcp
+```
+
+## License
+
+MIT

package/dist/YouAsked.d.ts

@@ -0,0 +1,40 @@
+import { type ReactNode } from "react";
+import { type YouAskedUser } from "./client";
+import { type Appearance } from "./theme";
+export declare const DEFAULT_API_URL = "https://api.youasked.dev";
+export type YouAskedProps = {
+    /** Publishable key (ya_pub_…). Safe to ship in client code. Not needed with `demo`. */
+    appKey?: string;
+    /**
+     * Runs entirely in the browser with sample requests and a pretend team, no network. Posting, voting,
+     * commenting and a reply a few seconds later all work. For docs, Storybook and landing pages.
+     */
+    demo?: boolean;
+    /** Who's asking. Leave out for anonymous visitors. */
+    user?: YouAskedUser | null;
+    /** hex HMAC-SHA256 of user.id with your secret key, made on your server (see `signUser`). */
+    signature?: string | null;
+    /** Set false while you're still fetching the signature; the widget waits instead of acting anonymously. */
+    ready?: boolean;
+    appearance?: Appearance;
+    /** "floating" adds a chat-style launcher in the corner. "none" if you use the inline entry points or your own buttons. */
+    trigger?: "floating" | "none";
+    position?: "bottom-right" | "bottom-left";
+    /** Text next to the launcher icon. Leave empty for an icon-only bubble. */
+    label?: string;
+    /** Your app's name in the greeting. Defaults to the name you created the app with. */
+    appName?: string;
+    /** Square image URL for your app's icon. By default it's found from the page (apple-touch-icon or a large favicon); false hides it. */
+    appIcon?: string | false;
+    /** First message on the home screen. */
+    greeting?: string;
+    /** Heading of the full list. */
+    title?: string;
+    /** Distance in px from the bottom edge for the launcher, toast and desktop panel, e.g. to clear a tab bar. */
+    offset?: number;
+    /** Show the corner card for replies, shipped requests and what's new. Turn off for previews embedded in a page. */
+    cards?: boolean;
+    apiUrl?: string;
+    children?: ReactNode;
+};
+export declare function YouAsked({ appKey, demo, cards, user, signature, ready, appearance, trigger, position, label, appName, appIcon, greeting, title, offset, apiUrl, children, }: YouAskedProps): import("react").JSX.Element;