microsoft
/
FluidFramework
зеркало из https://github.com/microsoft/FluidFramework.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Documentation updates (#1037)

This commit is contained in:
Tyler Butler 2020-01-27 10:08:10 -08:00 коммит произвёл GitHub
Родитель fa6dde632d
Коммит 9d39d93b03
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
86 изменённых файлов: 10477 добавлений и 1370 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

2
docs/.editorconfig
Просмотреть файл

@ -1,6 +1,8 @@
[*]
trim_trailing_whitespace = true
insert_final_newline = true
indent_style = space
indent_size = 4
[*.{json,md}]
indent_style = space

3
docs/.vscode/settings.json поставляемый Normal file
Просмотреть файл

@ -0,0 +1,3 @@
{
"git.ignoreLimitWarning": true
}

262
docs/.vuepress/config.js Normal file
Просмотреть файл

@ -0,0 +1,262 @@
/*!
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License.
*/
module.exports = {
title: "💧 Fluid Framework",
description: "State that flows",
evergreen: true,
plugins: [
["vuepress-plugin-check-md"],
["tabs"],
// [
// "vuepress-plugin-code-copy",
// {
// color: "#999",
// }
// ],
[
"vuepress-plugin-container",
{
type: "important",
defaultTitle: {
"/": "IMPORTANT"
},
},
],
[
"vuepress-plugin-container",
{
type: "note",
defaultTitle: {
"/": "NOTE"
},
},
],
],
markdown: {
anchor: {
permalink: true,
permalinkBefore: true,
permalinkSymbol: "💧"
},
lineNumbers: true,
extractHeaders: ["h2", "h3", "h4"],
extendMarkdown: (md) => {
// use additional markdown-it plugins
md.use(require("markdown-it-include"), "./includes/")
.use(require("markdown-it-deflist"));
}
},
themeConfig: {
docsDir: "docs",
editLinks: false,
lastUpdated: false, // "Last Updated",
repo: "microsoft/FluidFramework",
smoothScroll: true,
sidebarDepth: 1,
nav: [
{ text: "What is Fluid?", link: "/what-is-fluid" },
{ text: "Guide", link: "/guide/" },
{ text: "Tutorials", link: "/examples/" },
// { text: "Data Structures", link: "/dds/" },
{ text: "API", link: "/api/overview" },
{
text: "🤿 Dive Deeper",
items: [
{ text: "How Fluid works", link: "/how/" },
{ text: "FAQ", link: "/faq/" },
{ text: "Terminology", link: "/misc/terminology" },
{ text: "Concepts", link: "/misc/concepts" },
{
text: "Contributing",
items: [
{ text: "Coding guidelines", link: "/contributing/coding-guidelines" },
{ text: "Building documentation locally", link: "/contributing/building-documentation" },
{ text: "Routerlicious build machine", link: "/contributing/r11s-build-machine" },
]
}
]
},
],
sidebar: {
"/api/": [
{
title: "API Overview",
path: "overview",
collapsable: false,
sidebarDepth: 0
},
{
title: "Framework",
sidebarDepth: 2,
children: [
"fluid-aqueduct",
"fluid-aqueduct-react",
"fluid-component-core-interfaces",
"fluid-framework-interfaces",
"fluid-undo-redo",
]
},
{
title: "Distributed Data Structures",
children: [
"fluid-cell",
"fluid-ink",
"fluid-map",
"fluid-ordered-collection",
"fluid-register-collection",
"fluid-sequence",
"fluid-shared-object-base",
]
},
{
title: "Runtime",
children: [
"fluid-component-runtime",
"fluid-container-runtime",
"fluid-runtime-definitions",
]
},
{
title: "Loader",
children: [
"fluid-container-definitions",
"fluid-container-loader",
"fluid-execution-context-loader",
"fluid-web-code-loader",
]
},
{
title: "Driver",
children: [
"fluid-driver-base",
"fluid-driver-definitions",
"fluid-file-driver",
"fluid-iframe-driver",
"fluid-odsp-driver",
"fluid-replay-driver",
"fluid-routerlicious-driver",
]
},
{
title: "Sample Hosts",
children: [
"react-web-host",
"tiny-web-host",
"fluid-base-host",
]
},
{
title: "Tools",
children: [
"fluid-debugger",
"fluid-merge-tree-client-replay",
"fluid-replay-tool",
]
},
{
title: "Miscellaneous",
children: [
"fluid-core-utils",
]
},
{
title: "Internal/Deprecated",
children: [
"client-api",
"fluid-common-definitions",
"fluid-creation-driver",
"fluid-driver-utils",
"fluid-host-service-interfaces",
"fluid-runtime-utils",
]
},
],
"/guide/": [
{
title: "Guide",
collapsable: false,
children: [
"",
"yo-fluid",
"build-a-component",
"water-park",
]
},
{
title: "Distributed Data Structures",
collapsable: true,
path: "dds",
children: [
"SharedDirectory",
"SharedMap",
"SharedCell",
{
title: "Sequences",
path: "sequences",
children: [
"SharedNumberSequence",
"SharedObjectSequence",
"SharedString",
"SparseMatrix",
],
},
"consensus",
// {
// title: "Consensus",
// children: [
// "ConsensusQueue",
// "ConsensusRegisterCollection",
// "ConsensusStack",
// ],
// },
]
},
{
title: "Advanced",
collapsable: false,
children: [
"dds-anatomy",
]
},
],
"/examples/": [
{
title: "Components",
collapsable: true,
children: [
"visual-component",
"data-component",
"embed-components",
"cross-component",
"component-patterns",
"component-collections",
"bots",
"component-best-practices",
]
},
{
title: "Containers",
collapsable: true,
children: [
"singletons",
]
},
"examples",
"sudoku",
"yo-fluid-breakdown",
],
"/how/": [
"",
"tob",
"developer-guide",
],
"/advanced/": [
"",
"loading-deep-dive",
],
},
}
}

32
docs/.vuepress/styles/index.styl Normal file
Просмотреть файл

@ -0,0 +1,32 @@
@require '~vuepress-plugin-tabs/dist/themes/default.styl';
a.header-anchor:hover {
text-decoration: initial !important;
}
.home .hero .description {
color: $textColor !important;
}
.custom-block {
.custom-block-title {
font-weight: 600;
margin-bottom: -0.4rem;
}
&.important, &.tip, &.note {
padding: 0.1rem 1.5rem;
border-left-width: 0.5rem;
border-left-style: solid;
margin: 1rem 0;
background-color: #f3f5f7;
}
&.important, &.tip {
border-color: #00BCF2; // #0078d4
}
&.note {
border-color: #2c3e50;
}
}

22
docs/.vuepress/styles/palette.styl Normal file
Просмотреть файл

@ -0,0 +1,22 @@
// colors
// $accentColor = #3eaf7c;
$accentColor = darken(#00BCF2, 25%);
$textColor = #2c3e50;
$borderColor = #eaecef;
$codeBgColor = #282c34;
$arrowBgColor = #ccc;
// $badgeTipColor = #42b983;
$badgeTipColor = #00BCF2;
$badgeWarningColor = darken(#ffe564, 35%);
$badgeErrorColor = #DA5961;
// layout
$navbarHeight = 3.6rem;
$sidebarWidth = 20rem;
$contentWidth = 740px;
$homePageWidth = 960px;
// responsive breakpoints
$MQNarrow = 959px;
$MQMobile = 719px;
$MQMobileNarrow = 419px;

39
docs/Dockerfile
Просмотреть файл

@ -3,28 +3,6 @@
FROM node:10.16.0-slim AS base
# node-gyp and mono 6 dependencies
RUN apt-get update && apt-get install -y \
apt-transport-https \
ca-certificates \
dirmngr \
git \
gnupg \
unzip \
wget
# Install mono 6
RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
RUN echo "deb https://download.mono-project.com/repo/debian stable-stretch main" | tee /etc/apt/sources.list.d/mono-official-stable.list
RUN apt-get update && apt-get install -y mono-complete
# Download DocFX
WORKDIR /docfx
RUN wget https://github.com/dotnet/docfx/releases/download/v2.45.1/docfx.zip -nv
RUN unzip docfx.zip
WORKDIR /
#############################
# Copy the source and the api artifact
FROM base AS r11s
@ -34,29 +12,26 @@ COPY . .
#############################
FROM r11s AS docs
# Workaround for https://github.com/Microsoft/web-build-tools/issues/1229
WORKDIR /docs/api
RUN sed -i "s/SharePoint Framework reference/API overview/g" toc.yml
RUN sed -i "s/\~\/overview\/sharepoint.md/\~\/api_overview.md/g" toc.yml
WORKDIR /docs
RUN npm install
# Run DocFX
WORKDIR /docfx
RUN mono docfx.exe build ../docs/docfx.json
# Build
RUN npm run build:ci
#############################
FROM docs AS docpublish
WORKDIR /
RUN git config --global user.email "praguertdev@microsoft.com"
RUN git config --global user.name "Prague build server"
RUN git config --global user.email "fluidrtdev@microsoft.com"
RUN git config --global user.name "Fluid build server"
ARG DOCSGITPASSWORD
RUN git clone https://%24praguedocs:$DOCSGITPASSWORD@praguedocs.scm.azurewebsites.net:443/praguedocs.git praguedocs
WORKDIR /praguedocs
RUN git pull
WORKDIR /
RUN rsync docs/_site/ praguedocs/ -rv --exclude '.git'
RUN rsync docs/dist/ praguedocs/ -rv --exclude '.git'
WORKDIR /praguedocs
RUN git add .

68
docs/README.md Normal file
Просмотреть файл

@ -0,0 +1,68 @@
---
home: true
# heroImage: /hero.png
# heroText: Fluid Framework
# tagline: State that flows
# actionText: Get Started →
# actionLink: /guide/
# features:
# - title: Simplicity First
# details: Minimal setup with markdown-centered project structure helps you focus on writing.
# - title: Vue-Powered
# details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
# - title: Performant
# details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
# footer: "Made with ❤ in Redmond."
---
::: tip
The URL to this documentation is <https://aka.ms/fluid>.
:::
# Fluid Framework
Welcome to Fluid!
We built Fluid to make it simpler for developers to build real-time collaborative experiences using Web technology.
Fluid enables distributed, collaborative applications by providing developers with eventually consistent [distributed
data structures](./guide/dds.md), a flexible component and app model, and a reference server implementation called
[Routerlicious](./architecture/server/README.md).
Teams across Microsoft are using Fluid for low latency collaboration, zero setup data persistence, and on-by-default
cross app compatibility. Among other projects, our partner teams are building components for text editing, gaming,
command line tooling, and IOT.
Fluid's [distributed data structures](./guide/dds.md) make it easy to write apps that are collaborative just like you
would build single-user applications and experiences. Fluid handles keeping your data in sync across multiple clients,
so you can focus on your app's business logic. Fluid's data synchronization is fast, efficient, and requires very little
bandwidth. Fluid is extensible, too. You can write components which can be re-used or you can even create new
distributed data structures.
::: note What about Prague?
Prague was the code name for the Fluid Framework. Fluid is the name we'll use going forward.
`"Prague" === "Fluid" === "Fluid Framework"`
:::
## New to Fluid?
If you are new to the Fluid Framework, we recommend reading [What is Fluid?](./what-is-fluid.md) to orient yourself.
## Get started now
Get up and running quickly using our [Getting Started guide](./guide/README.md).
## Help
### Stack Overflow
The Fluid team answers **questions** on the [Microsoft Stack Overflow](https://stackoverflow.microsoft.com/) using
the [Fluid](https://stackoverflow.microsoft.com/questions/tagged/fluid) tag.
Bugs, suggestions, and issues should be directed to our [issues page](https://github.com/Microsoft/FluidFramework/issues).
Logistical questions can be directed to our [Teams group](https://teams.microsoft.com/l/team/19%3a10ccb94cae324ec2aabcd6b6322b1a25%40thread.skype/conversations?groupId=9ce27575-2f82-4689-abdb-bcff07e8063b&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47).

6
docs/advanced/toc.yml
Просмотреть файл

@ -1,6 +0,0 @@
- name: Advanced Topics
href: README.md
- name: "Anatomy of a Distributed Data Structure"
href: dds-anatomy.md
- name: Fluid Loading Deep Dive
href: loading-deep-dive.md

0
docs/api_overview.md → docs/api-pages/overview.md
Просмотреть файл

2
docs/architecture/README.md
Просмотреть файл

@ -12,7 +12,7 @@ Responsibilities of the server:
* Broadcast ops to all connected clients
* Data persistence
We provide a reference implementation of a Fluid server called <xref:r11s>.
We provide a reference implementation of a Fluid server called [Routerlicious](./server/README.md).
## Client

31
docs/architecture/server/README.md
Просмотреть файл

@ -21,7 +21,7 @@ pets](https://cloudscaling.com/blog/cloud-computing/the-history-of-pets-vs-cattl
## Architecture
![Routerlicious architecture diagram](./SystemArchitecture.JPG "System Diagram")
![Routerlicious architecture diagram](./SystemArchitecture.jpg "System Diagram")
### Microservices
@ -78,13 +78,13 @@ this interface are then able to plug into the system as a whole. Currently we ha
## Distributed data structures
See <xref:dds>
See [distributed data structures](../../guide/dds.md)
## Building and Running
Note that we also provide an npm package of our client side API which allows you to program against the production
Routerlicious service. See the [API documentation](xref:build-a-component) for more details. You only need to follow the
below steps if you'd like to run a local version of the service or need to make changes to it.
Routerlicious service. See the [API documentation](../../guide/build-a-component.md) for more details. You only need to
follow the below steps if you'd like to run a local version of the service or need to make changes to it.
### Prerequisities
@ -148,12 +148,13 @@ Docker Compose is used to run the service locally. To start up an instance of th
* `docker-compose build`
* `docker-compose up`
> [!TIP]
> The standalone app is meant to be run in a Linux container. If when running either of the above commands you get an
> error mentioning `no matching manifest for windows/amd64 in the manifest list entries`, check that your Docker
> installation is configured to run Linux containers. If you are using Docker for Windows, you can check this by
> right-clicking on the Docker icon in your taskbar. If you see the option `Switch to Linux containers...`, click this.
> If you see the option `Switch to Windows containers...`, you are already configured to run Linux containers.
::: tip
The standalone app is meant to be run in a Linux container. If when running either of the above commands you get an
error mentioning `no matching manifest for windows/amd64 in the manifest list entries`, check that your Docker
installation is configured to run Linux containers. If you are using Docker for Windows, you can check this by
right-clicking on the Docker icon in your taskbar. If you see the option `Switch to Linux containers...`, click this.
If you see the option `Switch to Windows containers...`, you are already configured to run Linux containers.
:::
### Testing
@ -216,7 +217,7 @@ exploration (i.e. branching, forking, merging documents).
To view the git stored snapshots simply run
```text
```
git clone ssh://git@localhost:3022/home/git/fluid/fluid
cd fluid/fluid
git checkout <document id>
@ -267,11 +268,11 @@ grafana up and running.
## Authentication model
Routerlicious uses a token based authentication model. Tenants are registered to routerlicious first and a secret key is
generated for each tenant. Apps are expected to pass <secret-key>, <tenant-id>, and <user-info> as a signed token to
routerlicious. Tenants are given a symmetric-key beforehand to sign the token.
Routerlicious uses a token based authentication model. Tenants are registered to Routerlicious first and a secret key is
generated for each tenant. Apps are expected to pass `<secret-key>`, `<tenant-id>`, and `<user-info>` as a signed token
to Routerlicious. Tenants are given a symmetric-key beforehand to sign the token.
When a user from a tenant wants to create/access a document in routerlicious, it passes the signed token in api load
When a user from a tenant wants to create/access a document in Routerlicious, it passes the signed token in api load
call. Routerlicious verifies the token, matches the secret-key for the tenant and on a successful verification, grants
the user access to the document. The access token is valid for the entire websocket session. User is expected to pass in
another signed token for any subsequent api load call.

10
docs/architecture/toc.yml
Просмотреть файл

@ -1,10 +0,0 @@
- name: Architecture
href: README.md
items:
- name: "Routerlicious - Reference server"
href: server/README.md
- name: Components
href: components/README.md
items:
- name: Design principles
href: components/design-principles.md

96
docs/buildDocs.js Normal file
Просмотреть файл

@ -0,0 +1,96 @@
/*!
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License.
*/
const { readdir, createReadStream, writeFile } = require("fs-extra");
const { createInterface } = require("readline");
const { join, parse } = require("path");
const { exec } = require("child_process");
const getFirstLine = require("firstline");
// This script is modified from a version in faast.js' build system
//
// https://github.com/faastjs/faast.js/blob/master/build/make-docs.js
//
// It's used to rewrite some parts of the generated docs from api-generator and api-documenter.
async function main() {
// await new Promise((resolve, reject) =>
// exec(
// "api-extractor run --local && api-documenter markdown -i dist -o docs/api",
// (err, stdout, stderr) => {
// console.log(stdout);
// console.error(stderr);
// if (err) {
// reject(err);
// } else {
// resolve();
// }
// }
// )
// );
const dir = "./api";
const docFiles = await readdir(dir);
for (const docFile of docFiles) {
try {
const { name: id, ext } = parse(docFile);
if (ext !== ".md" && ext !== ".mdx") {
continue;
}
const docPath = join(dir, docFile);
const firstLine = await getFirstLine(docPath);
if(!firstLine.startsWith("<!--")) {
continue;
}
const input = createReadStream(docPath);
const output = [];
const lines = createInterface({
input,
crlfDelay: Infinity
});
let title = "";
lines.on("line", line => {
let skip = false;
if (!title) {
const titleLine = line.match(/## (.*)/);
if (titleLine) {
title = titleLine[1];
}
}
const homeLink = line.match(/\[Home\]\(.\/index\.md\) &gt; (.*)/);
if (homeLink) {
// Skip the breadcrumb for the toplevel index file.
if (id !== "faastjs") {
output.push(homeLink[1]);
}
skip = true;
}
if (!skip) {
output.push(line);
}
});
await new Promise(resolve => lines.once("close", resolve));
input.close();
const header = [
"---",
`id: ${id}`,
`title: ${title}`,
// `hide_title: true`,
"---"
];
await writeFile(docPath, header.concat(output).join("\n"));
} catch (err) {
console.error(`Could not process ${docFile}: ${err}`);
}
}
}
main();

42
docs/contributing/building-documentation.md
Просмотреть файл

@ -10,39 +10,17 @@ npm run build
npm run build:docs
```
This will create many YAML files under `docs/api/`.
This will create many Markdown files under `docs/api/`. These files should *not* be committed to git.
> [!IMPORTANT]
> Due to <https://github.com/Microsoft/web-build-tools/issues/1229>, `api-documenter` outputs a
> `toc.yaml` file like this:
>
> ```yaml
> items:
> - name: SharePoint Framework reference
> href: ~/overview/sharepoint.md
> items:
> - name: sequence
> uid: sequence
> items:
> - name: Interval
> uid: sequence.Interval
> ```
>
> You need to manually remove the first 3 lines, so you end up with something like this:
>
> ```yaml
> items:
> - name: sequence
> uid: sequence
> items:
> - name: Interval
> uid: sequence.Interval
> ```
## Building documentation site with Vuepress
## Building documentation site with DocFX
To build the docs themselves, you'll need to switch to the `docs/` folder, install the dependencies, and then build the
site.
Finally, to build the docs themselves, you'll need [DocFX](https://dotnet.github.io/docfx/).
Run `docfx build` from the docs directory. The built docs are put in `docs/_site`.
```bash
cd docs
npm install
npm start
```
You can also serve the docs from http://localhost:8080/ by adding `--serve` to the command.
I.e. `docfx build --serve`
`npm start` will serve the local documentation from http://localhost:8080/.

23
docs/contributing/contributing-to-documentation.md
Просмотреть файл

@ -1,23 +0,0 @@
# Contributing to documentation
## Contributing API documentation
Simply add TSDoc comments to the source code; those will be automatically pulled out and included in the published
documentation.You can do a local build using DocFX if you want to see how things look before you push.
## Editing an existing documentation file
The docs include an "Improve this Doc" button that will navigate you to the Markdown file in GitHub, where you can
edit it directly and create a PR with the changes if needed.
## Adding a brand new topic (i.e. a Markdown file)
There are two steps to adding a completely new file: Adding the file, and updating the TOC to include it. Adding
the file is simple; just place a new Markdown file in the `docs` folder. Then update the `toc.yml` file in the
docs folder to include a link to your new file.
## Add a new section (i.e. a 'hub' for multiple topics)
Similar to adding a new file, adding a new section takes multiple steps. First, you add a new folder for the section,
then create an `index.md` and `toc.yml` file within it. Finally, you need to update the root `toc.yml` file to
include the new section.

7
docs/contributing/r11s-build-machine.md
Просмотреть файл

@ -1,7 +1,8 @@
# Build Server
> [!TIP]
> This topic is only relevant to core Fluid contributors.
::: important
This topic is only relevant to core Fluid contributors.
:::
Install Docker Community Edition in order to run the following
<https://docs.docker.com/install/linux/docker-ce/ubuntu/#set-up-the-repository>
@ -15,7 +16,7 @@ a Hyper-V VM. If setting up inside of a VM make sure to allocate enough vCPUs.
Then run the following command after getting a VSTS token:
```text
```
docker run \
-d \
--restart unless-stopped \

10
docs/contributing/toc.yml
Просмотреть файл

@ -1,10 +0,0 @@
- name: How to contribute
href: README.md
- name: Coding guidelines
href: coding-guidelines.md
- name: Contributing to documentation
href: contributing-to-documentation.md
- name: Building documentation locally
href: building-documentation.md
- name: Build machine set up
href: r11s-build-machine.md

69
docs/docfx.json
Просмотреть файл

@ -1,69 +0,0 @@
{
"build": {
"content": [
{
"files": [
"**.md",
"**.yml"
],
"exclude": [
"_site/**",
"templates/**",
"legacy/**"
]
},
{
"src": "../",
"files": [
"samples/hosts/literate/README.md",
"packages/drivers/fluid-debugger/README.md",
"packages/tools/fluid-fetch/README.md",
"packages/tools/replay-tool/README.md"
],
"exclude": [
"**/node_modules/**"
]
}
],
"resource": [
{
"files": [
"images/**",
"examples/**/*.html",
"**.png",
"**.jpg"
]
},
{
"src": "../",
"files": [
"packages/drivers/fluid-debugger/images/**.jpg"
],
"exclude": [
"**/node_modules/**"
]
}
],
"dest": "_site",
"globalMetadata": {
"_appTitle": "Fluid Documentation",
"_enableSearch": true,
"_gitContribute": {
"repo": "https://github.com/Microsoft/FluidFramework",
"branch": "master"
}
},
"globalMetadataFiles": [],
"fileMetadataFiles": [],
"template": [
"default",
"templates/fluid"
],
"postProcessors": [],
"markdownEngineName": "dfm-latest",
"noLangKeyword": false,
"keepFileLink": false,
"cleanupCacheHistory": false,
"disableGitFeatures": false
}
}

53
docs/examples/README.md
Просмотреть файл

@ -1,55 +1,12 @@
---
uid: examples
---
# Examples
# Tutorials
You can find a number of examples in the Fluid repo, under the
[samples/chaincode](https://github.com/Microsoft/FluidFramework/tree/master/samples/chaincode)
path. The following is a list of good examples to start with.
## Components
Also see <xref:yo-fluid-details>.
## Clicker
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/clicker)
## Using the Distributed data structures
**Complexity:** Simple
### SharedMap
**UI library:** React
**Distributed data structures:**
- SharedMap
- Counter
Clicker is a simple example to familiarize yourself with Fluid's component scaffolding. It uses React for rendering.
## Todo
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/todo)
**Complexity:** Intermediate
**UI library:** React
**Distributed data structures:**
- SharedMap
- SharedString
- SharedCell
Todo demonstrates subcomponents and using Fluid's routing capabilities to enable an individual todo item to be embedded
in a different canvas.
## ProgressBar
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/todo)
## ImageGallery
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/image-gallery)
## Pond
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/pond)
- [Sudoku](./sudoku.md)

3
docs/examples/bots.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# Bots
## NOT YET WRITTEN

3
docs/examples/component-best-practices.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# Best practices for when to use a component
## NOT YET WRITTEN

3
docs/examples/component-collections.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# Component collections
## NOT YET WRITTEN

6
docs/examples/component-patterns.md Normal file
Просмотреть файл

@ -0,0 +1,6 @@
# Component patterns
## Singleton components
### NOT YET WRITTEN

3
docs/examples/cross-component.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# Interface paradigms and interacting across Components
## NOT YET WRITTEN

3
docs/examples/data-component.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# How to write a non-visual component
## NOT YET WRITTEN

3
docs/examples/embed-components.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# How to embed a component within another component
## NOT YET WRITTEN

55
docs/examples/examples.md Normal file
Просмотреть файл

@ -0,0 +1,55 @@
---
uid: examples
---
# Examples
You can find a number of examples in the Fluid repo, under the
[samples/chaincode](https://github.com/Microsoft/FluidFramework/tree/master/samples/chaincode)
path. The following is a list of good examples to start with.
Also see [the yo fluid breakdown](./yo-fluid-breakdown.md).
## Clicker
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/clicker)
**Complexity:** Simple
**UI library:** React
**Distributed data structures:**
- SharedMap
- Counter
Clicker is a simple example to familiarize yourself with Fluid's component scaffolding. It uses React for rendering.
## Todo
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/todo)
**Complexity:** Intermediate
**UI library:** React
**Distributed data structures:**
- SharedMap
- SharedString
- SharedCell
Todo demonstrates subcomponents and using Fluid's routing capabilities to enable an individual todo item to be embedded
in a different canvas.
## ProgressBar
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/todo)
## ImageGallery
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/image-gallery)
## Pond
[Source code](https://github.com/Microsoft/FluidFramework/tree/release/0.6/packages/components/pond)

3
docs/examples/singletons.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# Singleton components
## NOT YET WRITTEN

67
docs/examples/sudoku-example.md → docs/examples/sudoku.md
Просмотреть файл

@ -25,7 +25,7 @@ Keller (<https://github.com/ffflorian>).
The project has the following folder layout:
```text
```
└───src
| fluidSudoku.tsx
│ index.ts
@ -48,13 +48,14 @@ development server, which will load two instances of the component side by side.
![The Sudoku component loaded in the Fluid development server](./sudoku-side-by-side.png "Sudoku component")
> [!IMPORTANT]
>
> If you make changes to your data model during development, you may notice console failures, or your component may fail
> to load completely, when you refresh localhost:8080. This is caused when the local code tries to load a Fluid data
> model that uses a schema different than what the code expects. You can force a fresh Fluid document, and by extension,
> an empty schema, by reloading <http://localhost:8080/>. This will redirect you to a new random Fluid document.
::: important
If you make changes to your data model during development, you may notice console failures, or your component may fail
to load completely, when you refresh localhost:8080. This is caused when the local code tries to load a Fluid data model
that uses a schema different than what the code expects. You can force a fresh Fluid document, and by extension, an
empty schema, by reloading <http://localhost:8080/>. This will redirect you to a new random Fluid document.
:::
# Deep dive
@ -74,14 +75,15 @@ readonly correctValue: number // Stores the correct value of the cell
readonly coordinate: CoordinateString // The coordinate of the cell, as a comma-separated string, e.g. "2,3"
```
> [!IMPORTANT]
>
> Objects that are stored in distributed data structures, as `SudokuCell` is, must be safely JSON-serializable. This
> means that you cannot use functions or TypeScript class properties with these objects, because those are not
> JSON-serialized.
>
> One pattern to address this is to define static functions that accept the object as a parameter and manipulate it. See
> the `SudokuCell` class in `/src/helpers/sudokuCell.ts` for an example of this pattern.
::: important
Objects that are stored in distributed data structures, as `SudokuCell` is, must be safely JSON-serializable. This means
that you cannot use functions or TypeScript class properties with these objects, because those are not JSON-serialized.
One pattern to address this is to define static functions that accept the object as a parameter and manipulate it. See
the `SudokuCell` class in `/src/helpers/sudokuCell.ts` for an example of this pattern.
:::
## Rendering
@ -240,12 +242,15 @@ handled.
Let's look at the `numericInput` function, which is called when the user keys in a number.
> [!NOTE]
> The `numericInput` function can be found in the `SimpleTable` React component within `src/react/sudokuView.tsx`.
> `SimpleTable` is a helper React component that is not exported; you can consider it part of the `SudokuView` React
> component.
::: note
```typescript
The `numericInput` function can be found in the `SimpleTable` React component within `src/react/sudokuView.tsx`.
`SimpleTable` is a helper React component that is not exported; you can consider it part of the `SudokuView` React
component.
:::
```typescript{2-6,9}
const numericInput = (keyString: string, coord: string) => {
let valueToSet = Number(keyString);
valueToSet = Number.isNaN(valueToSet) ? 0 : valueToSet;
@ -268,7 +273,7 @@ const numericInput = (keyString: string, coord: string) => {
};
```
Lines 2-7 ensure we only accept single-digit numeric values. In line 9, we retrieve the coordinate of the cell from a DOM
Lines 2-6 ensure we only accept single-digit numeric values. In line 9, we retrieve the coordinate of the cell from a DOM
attribute that we added during render. Once we have the coordinate, which is a key in the `SharedMap` storing our Sudoku
data, we retrieve the cell data by calling `.get<SudokuCell>(coord)`. We then update the cell's value and set whether it
is correct. Finally, we call `.set(key, toSet)` to update the data in the `SharedMap`.
@ -322,7 +327,7 @@ First, you need to create a `SharedMap` for your presence data.
this.root.set(this.presenceMapKey, clientPresence.handle);
```
Notice that the Fluid runtime is exposed via the `this.runtime` property provided by [PrimedComponents][].
Notice that the Fluid runtime is exposed via the `this.runtime` property provided by [PrimedComponent][].
1. Inside the `componentHasInitialized` method, add the following code to the bottom of the method to retrieve the
presence map when the component initializes:
@ -427,16 +432,16 @@ Now that you have some experience with Fluid, are there other features you could
you could extend it to display a client name in the cell to show client-specific presence. Or you could use the
[undo-redo][] package to add undo/redo support!
If you want to build your own component, check out <xref:yo-fluid>.
If you want to build your own component, check out [yo fluid](../guide/yo-fluid.md).
See <xref:examples> for more examples.
See [Examples](./examples.md) for more examples.
<!-- Links -->
[IComponentHTMLVisual]: xref:@microsoft/fluid-component-core-interfaces!IComponentHTMLVisual:interface
[IComponentReactViewable]: xref:@microsoft/fluid-aqueduct-react!IComponentReactViewable:interface
[IProvideComponentHTMLVisual]: xref:@microsoft/fluid-component-core-interfaces!IProvideComponentHTMLVisual:interface
[PrimedComponent]: xref:@microsoft/fluid-aqueduct!PrimedComponent:class
[SharedDirectory]: xref:@microsoft/fluid-map!SharedDirectory:class
[SharedMap]: xref:@microsoft/fluid-map!SharedMap:class
[undo-redo]: xref:@microsoft/fluid-undo-redo!
[IComponentHTMLVisual]: ../api/fluid-component-core-interfaces.IComponentHTMLVisual.md
[IComponentReactViewable]: ../api/fluid-aqueduct-react.IComponentReactViewable.md
[IProvideComponentHTMLVisual]: ../api/fluid-component-core-interfaces.IProvideComponentHTMLVisual.md
[PrimedComponent]: ../api/fluid-aqueduct.PrimedComponent.md
[SharedDirectory]: ../api/fluid-map.SharedDirectory.md
[SharedMap]: ../api/fluid-map.SharedMap.md
[undo-redo]: ../api/fluid-undo-redo.md

8
docs/examples/toc.yml
Просмотреть файл

@ -1,8 +0,0 @@
- name: Examples
href: README.md
- name: Yo Fluid Breakdown
href: yo-fluid-breakdown.md
- name: Sudoku component
href: sudoku-example.md
- name: Loaders
topicUid: loaders

3
docs/examples/visual-component.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# How to write a visual component
## NOT YET WRITTEN

64
docs/examples/yo-fluid-breakdown.md
Просмотреть файл

@ -1,16 +1,20 @@
---
uid: yo-fluid-details
sidebarDepth: 2
---
# Yo Fluid Breakdown
Congratulations, you've used <xref:yo-fluid> to create your first component! If you haven't done this yet, head over to <xref:yo-fluid>.
Congratulations, you've used [yo fluid](../guide/yo-fluid.md) to create your first component! If you haven't done this
yet, head over to [yo fluid](../guide/yo-fluid.md).
[[toc]]
## Creation options
<xref:yo-fluid> allows you to create a Fluid component either using React or just vanilla JavaScript.
[yo fluid](../guide/yo-fluid.md) allows you to create a Fluid component either using React or just vanilla JavaScript.
```text
```
? Which experience would you like to start with?
> react
vanillaJS
@ -19,7 +23,7 @@ Congratulations, you've used <xref:yo-fluid> to create your first component! If
You'll also get the option to customize your container. If this is your first time building a component, we recommend
choosing "no" for this option (we'll explain this option further below).
```text
```
? Do you want to customize your container (advanced)?
> no
yes
@ -36,9 +40,10 @@ Below we will walk through both the vanillaJS and the React examples.
First we will declare all our imports. Here is a quick description and use cases for each is discussed further below.
`PrimedComponent` and `PrimedComponentFactory` from <xref:@microsoft/fluid-aqueduct!> provide helper functionality.
`IComponentHTMLVisual` from <xref:@microsoft/fluid-component-core-interfaces!> provides the interface for enabling
rendering. `React` and `ReactDOM` are _only for React_ and enable React use.
`PrimedComponent` and `PrimedComponentFactory` from [@microsoft/fluid-aqueduct](../api/fluid-aqueduct.md) provide helper
functionality. `IComponentHTMLVisual` from
[@microsoft/fluid-component-core-interfaces](../api/fluid-component-core-interfaces.md) provides the interface for
enabling rendering. `React` and `ReactDOM` are _only for React_ and enable React use.
```typescript
import {
@ -57,12 +62,12 @@ Below we define our component class `ExampleFluidComponent`.
#### PrimedComponent
Extending <xref:@microsoft/fluid-aqueduct!PrimedComponent:class> sets up our component with required default behavior as
well as additional helpers to make component development easier.
Extending [PrimedComponent](../api/fluid-aqueduct.PrimedComponent.md) sets up our component with required default
behavior as well as additional helpers to make component development easier.
#### Key benefits
##### Key benefits
1. Setup a `root` <xref:@microsoft/fluid-map!SharedDirectory:class> (a Distributed Data Structure) that we can use to
1. Setup a `root` [SharedDirectory](../api/fluid-map.SharedDirectory.md) (a Distributed Data Structure) that we can use to
store collaborative content and other distributed data structures.
2. Provide `this.createAndAttachComponent(...)` and `this.getComponent(...)` functions for easier creation and access
to other components.
@ -73,10 +78,10 @@ well as additional helpers to make component development easier.
#### IComponentHTMLVisual
Implementing the <xref:@microsoft/fluid-component-core-interfaces!IComponentHTMLVisual:interface> interface denotes that
our component can render an HTML view. Throughout the Fluid Framework we define interfaces as a way to state our
behavior. Whoever is attempting to use this component can know we support this interface and therefore it will have a
`render(...)` function. View rendering is explained more below.
Implementing the [IComponentHTMLVisual](../api/fluid-component-core-interfaces.IComponentHTMLVisual.md) interface
denotes that our component can render an HTML view. Throughout the Fluid Framework we define interfaces as a way to
state our behavior. Whoever is attempting to use this component can know we support this interface and therefore it will
have a `render(...)` function. View rendering is explained more below.
#### Code
@ -112,11 +117,14 @@ protected async componentInitializingFirstTime() {
`render(div: HTMLElement)` is the implementation of `IComponentHTMLVisual`. The caller provides an `HTMLElement` that the
Component can use to render into. Every time `render(...)` is called we should produce a new view.
> [!NOTE]
> This is the point where React and vanillaJS differ.
::: note
#### [React Implementation](#tab/tabid-1)
This is the point where React and VanillaJS differ.
:::
:::: tabs
::: tab React
We create a `rerender` function that will display our content into the provided `HTMLElement`.
To get the dice value we use the `get` method on the root, using the same key (`diceValue`) that
we created in `componentInitializingFirstTime()`. Because we are using React we will call
@ -151,8 +159,8 @@ this.root.on("valueChanged", () => {
});
```
#### [VanillaJS Implementation](#tab/tabid-2)
:::
::: tab VanillaJS
The VanillaJS implementation is similar in many ways to the React version.
We create our component's DOM structure in `this.createComponentDom(div);` which creates the span that
@ -187,7 +195,8 @@ this.root.on("valueChanged", () => {
});
```
***
:::
::::
To set the value of the dice after rolling, we use the `set` method on the root, using the same
key `diceValue` as before. The helper functions used look like this:
@ -211,9 +220,9 @@ new instance. We require having an instantiation factory because it's required t
distributed data structures up front. Defining all the DDSs up front allows for the Fluid Framework to load
from a snapshot without worrying that something might exist in the snapshot that the framework can't understand.
In the example below we use the <xref:@microsoft/fluid-aqueduct!PrimedComponentFactory:class> as a helper to create our
instantiation factory. As properties we pass in our supported distributed data structures. In this scenario we don't use
any additional distributed data structures, so we pass an empty array.
In the example below we use the [PrimedComponentFactory](../api/fluid-aqueduct.PrimedComponentFactory.md) as a helper to
create our instantiation factory. As properties we pass in our supported distributed data structures. In this scenario
we don't use any additional distributed data structures, so we pass an empty array.
```typescript
[],
@ -242,7 +251,7 @@ If you instead chose to customize your container during the `yo fluid` setup, a
### Factory export
Instead of exporting the `PrimedComponentFactory` directly as the `fluidExport`, we'll instead export this factory
for use in the container we're customizing (in [index.ts](#index.ts)).
for use in the container we're customizing (in [index.ts](#index-ts)).
```typescript
export const ExampleFluidComponentInstantiationFactory = new PrimedComponentFactory(
@ -251,8 +260,6 @@ export const ExampleFluidComponentInstantiationFactory = new PrimedComponentFact
);
```
<a name="index.ts" />
### `index.ts`
You'll also have a file `./src/index.ts` for the container. In this file we define a registry of supported components.
@ -275,7 +282,8 @@ const componentName = pkg.name as string;
Finally we use `SimpleModuleInstantiationFactory` to create the `fluidExport`. The factory takes a default component
name `componentName` that is used to load the default component. It also takes the registry of components pointing to
the creation factory. In our case just our one component (`[componentName, Promise.resolve(ExampleFluidComponentInstantiationFactory)]`).
the creation factory. In our case just our one component
(`[componentName, Promise.resolve(ExampleFluidComponentInstantiationFactory)]`).
```typescript
export const fluidExport = new SimpleModuleInstantiationFactory(

4
docs/faq/README.md Normal file
Просмотреть файл

@ -0,0 +1,4 @@
# Frequently asked questions
## Where can I get help with Fluid?

8
docs/get-started/ConsensusQueue.md
Просмотреть файл

@ -1,8 +0,0 @@
---
uid: ConsensusQueue
---
# ConsensusQueue
- Package: <xref:@microsoft/fluid-ordered-collection!>
- API documentation: <xref:@microsoft/fluid-ordered-collection!ConsensusQueue:class>

8
docs/get-started/ConsensusRegisterCollection.md
Просмотреть файл

@ -1,8 +0,0 @@
---
uid: ConsensusRegisterCollection
---
# ConsensusRegisterCollection
- Package: <xref:@microsoft/fluid-register-collection!>
- API documentation: <xref:@microsoft/fluid-register-collection!ConsensusRegisterCollection:class>

8
docs/get-started/ConsensusStack.md
Просмотреть файл

@ -1,8 +0,0 @@
---
uid: ConsensusStack
---
# ConsensusStack
- Package: <xref:@microsoft/fluid-ordered-collection!>
- API documentation: <xref:@microsoft/fluid-ordered-collection!ConsensusStack:class>

66
docs/get-started/SharedDirectory.md
Просмотреть файл

@ -1,66 +0,0 @@
---
uid: SharedDirectory
---
# SharedDirectory and IDirectory
- Package: <xref:@microsoft/fluid-map!>
- API documentation:
- <xref:@microsoft/fluid-map!SharedDirectory:class>
- <xref:@microsoft/fluid-map!IDirectory:interface>
The SharedDirectory distributed data structure is similar to a <xref:SharedMap> and can be used to store key-value
pairs. In addition to the typical Map functionality for getting, setting, and iterating over values, SharedDirectory
provides a hierarchical organization of map-like data structures as SubDirectories. The values stored within can be
accessed like a map, and the hierarchy can be navigated using path syntax. SubDirectories can be retrieved for use as
working directories. This subdirectory tree can be used to give hierarchical structure to stored key/value pairs rather than
storing them on a flat map. Both the `SharedDirectory` and any subdirectories are `IDirectories`.For example:
```ts
mySharedDirectory
.createSubDirectory("a")
.createSubDirectory("b")
.createSubDirectory("c")
.set("foo", val1);
const mySubDir = mySharedDirectory.getWorkingDirectory("/a/b/c");
mySubDir.get("foo"); // returns val1
```
It provides the same API for setting and
retrieving values that JavaScript developers are accustomed to with the
[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) built-in object.
## Creation
To create a `SharedDirectory`, call the static create method:
```typescript
const myDirectory = SharedDirectory.create(this.runtime, id);
```
## Usage
The map operations on an `IDirectory` refer to the key/value pairs stored in that `IDirectory`, and function just like
<xref:SharedMap> including the same restrictions on keys and values. To operate on the subdirectory structure, use the
corresponding subdirectory methods.
<xref:@microsoft/fluid-map!IDirectory%23getWorkingDirectory:member(1)>
To "navigate" the subdirectory structure, `IDirectory` provides a
<xref:@microsoft/fluid-map!IDirectory%23getWorkingDirectory:member(1)> method which takes a relative path and returns the
`IDirectory` located at that path if it exists.
[!INCLUDE [object-serialization](../includes/object-serialization.md)]
SharedDirectory keys are _last write wins_; this behavior works well with few infrequent writers and many readers. In cases
with many frequent writers it's best to design your use of the directory such that each writer writes to its own keys so
they don't overwrite each other.
## Eventing
[valueChanged](<xref:@microsoft/fluid-map!SharedDirectory%23on:member(2)>) events additionally provide the absolute path
to the subdirectory storing the value that changed.
## Related distributed data structures
- <xref:SharedMap>

32
docs/get-started/SharedNumberSequence.md
Просмотреть файл

@ -1,32 +0,0 @@
---
uid: SharedNumberSequence
---
# SharedNumberSequence
- Package: <xref:@microsoft/fluid-sequence!>
- API documentation: <xref:@microsoft/fluid-sequence!SharedNumberSequence:class>
The SharedNumberSequence distributed data structure can be used to store sequences of numbers.
## Creation
To create a `SharedNumberSequence`, call the static create method:
```typescript
const mySequence = SharedNumberSequence.create(this.runtime, id);
```
## Usage
Like all SharedSequences, you can use the <xref:@microsoft/fluid-sequence!SharedSequence%23insert:member(1)> and
<xref:@microsoft/fluid-sequence!SharedSequence%23getItems:member(1)> methods to insert and retrieve items from the
sequence, and <xref:@microsoft/fluid-sequence!SharedSequence%23remove:member(1)> to remove items.
## Eventing
- [valueChanged](<xref:@microsoft/fluid-sequence!SharedSegmentSequence%23on:member(3)>)
## Related distributed data structures
- <xref:SharedObjectSequence>

34
docs/get-started/SharedObjectSequence.md
Просмотреть файл

@ -1,34 +0,0 @@
---
uid: SharedObjectSequence
---
# SharedObjectSequence
- Package: <xref:@microsoft/fluid-sequence!>
- API documentation: <xref:@microsoft/fluid-sequence!SharedObjectSequence:class>
The SharedObjectSequence distributed data structure can be used to store sequences of objects.
## Creation
To create a `SharedObjectSequence`, call the static create method:
```typescript
const mySequence = SharedObjectSequence.create(this.runtime, id);
```
## Usage
Like all SharedSequences, you can use the <xref:@microsoft/fluid-sequence!SharedSequence%23insert:member(1)> and
<xref:@microsoft/fluid-sequence!SharedSequence%23getItems:member(1)> methods to insert and retrieve items from the sequence, and
<xref:@microsoft/fluid-sequence!SharedSequence%23remove:member(1)> to remove items.
[!INCLUDE [object-serialization](../includes/object-serialization.md)]
## Eventing
- [valueChanged](<xref:@microsoft/fluid-sequence!SharedSegmentSequence%23on:member(3)>)
## Related distributed data structures
- <xref:SharedNumberSequence>

14
docs/get-started/SharedString.md
Просмотреть файл

@ -1,14 +0,0 @@
---
uid: SharedString
---
# SharedString
- Package: <xref:@microsoft/fluid-sequence!>
- API documentation: <xref:@microsoft/fluid-sequence!SharedString:class>
## Usage
The content for this section will come from this [source document][1].
[1]: https://github.com/microsoft/FluidFramework/blob/master/packages/runtime/sequence/readme.md

11
docs/get-started/dds.md
Просмотреть файл

@ -1,11 +0,0 @@
---
uid: dds
---
# Distributed Data Structures
The content for this section will come from this [source document][1].
[1]: https://microsoft.sharepoint.com/:w:/t/Prague/EbN0Q0YfRpxLhvu71KvtpacBWAUoOm88XDRXd_p-6GfmfQ?e=3DckiM
<iframe src="https://microsoft.sharepoint.com/teams/Prague/_layouts/15/Doc.aspx?sourcedoc={464374b3-461f-4b9c-86fb-bbd4abeda5a7}&amp;action=embedview&amp;wdStartOn=1" width="695px" height="1000px" frameborder="0">This is an embedded <a target="_blank" href="https://office.com">Microsoft Office</a> document, powered by <a target="_blank" href="https://office.com/webapps">Office</a>.</iframe>

39
docs/get-started/toc.yml
Просмотреть файл

@ -1,39 +0,0 @@
- name: Get started
href: README.md
items:
- name: Yo fluid
href: yo-fluid.md
- name: Build a component
href: build-a-component.md
- name: Water Park
href: water-park.md
- name: Developer Guide
href: developer-guide.md
- name: Concepts
href: concepts.md
items:
- name: Distributed Data Structures
href: dds.md
items:
- name: SharedDirectory
href: SharedDirectory.md
- name: SharedMap
href: SharedMap.md
- name: SharedNumberSequence
href: SharedNumberSequence.md
- name: SharedObjectSequence
href: SharedObjectSequence.md
- name: SharedString
href: SharedString.md
- name: SharedCell
href: SharedCell.md
- name: ConsensusQueue
href: ConsensusQueue.md
- name: ConsensusRegisterCollection
href: ConsensusRegisterCollection.md
- name: ConsensusStack
href: ConsensusStack.md
- name: Total Order Broadcast & Eventual Consistency
href: tob.md
- name: Terminology
href: terminology.md

16
docs/get-started/water-park.md
Просмотреть файл

@ -1,16 +0,0 @@
---
uid: water-park
---
# The Component Water Park
> [!WARNING]
> This documentation is based on an earlier version of the Fluid Framework and is outdated.
>
> Track the documentation update with [#104](https://github.com/microsoft/FluidFramework/issues/104).
The Fluid Component Water Park is a place to explore, test, and share components. It can load any component made with
<xref:yo-fluid> and published to Verdaccio. `yo fluid` provides instructions on how to publish your components to
Verdaccio.
[Visit the Water Park](https://aka.ms/fluidwaterpark) to get started.

49
docs/get-started/yo-fluid.md
Просмотреть файл

@ -1,49 +0,0 @@
---
uid: yo-fluid
---
# yo fluid
yo fluid is a tool that helps create a scaffold for a Fluid component.
First, [clone the Fluid Framework repo locally](./README.md#fluid-repo).
Once you've cloned the repo, you can set up the `yo fluid` bootstrapper:
```text
npm install -g yo
cd /FluidFramework/tools/generator-fluid
npm install
npm link
```
This will install yo fluid along with its dependency, [Yeoman](https://yeoman.io/).
Yo fluid is now ready. Use it to scaffold a new component by typing `yo fluid` and following the instructions.
> [!TIP]
> if you get an error when running `yo fluid` saying that a generator cannot be found, try using `yo @microsoft/fluid` instead.
## Next steps
Now that you've used yo fluid to scaffold a new component, you should examine the contents of the yo fluid output.
Or you can jump right in to [building your own component](xref:build-a-component) using the scaffold as a base.
## Anatomy of the yo fluid scaffold
See <xref:yo-fluid-details>
Now you're ready to <xref:build-a-component>!
> [!TIP]
> For yo fluid setup issues see [this question on Microsoft Stack
> Overflow](https://stackoverflow.microsoft.com/questions/137930/npm-install-fails-with-auth-issues/137931#137931)
## Source code
The source code for the yo fluid generator can be found at
<https://github.com/Microsoft/FluidFramework/blob/master/tools/generator-fluid/>.

8
docs/guide/ConsensusQueue.md Normal file
Просмотреть файл

@ -0,0 +1,8 @@
---
uid: ConsensusQueue
---
# ConsensusQueue
- Package: [@microsoft/fluid-ordered-collection](../api/fluid-ordered-collection.md)
- API documentation: [ConsensusQueue](../api/fluid-ordered-collection.ConsensusQueue.md)

8
docs/guide/ConsensusRegisterCollection.md Normal file
Просмотреть файл

@ -0,0 +1,8 @@
---
uid: ConsensusRegisterCollection
---
# ConsensusRegisterCollection
- Package: [@microsoft/fluid-register-collection](../api/fluid-register-collection.md)
- API documentation: [ConsensusRegisterCollection](../api/fluid-register-collection.ConsensusRegisterCollection.md)

8
docs/guide/ConsensusStack.md Normal file
Просмотреть файл

@ -0,0 +1,8 @@
---
uid: ConsensusStack
---
# ConsensusStack
- Package: [@microsoft/fluid-ordered-collection](../api/fluid-ordered-collection.md)
- API documentation: [ConsensusStack](../api/fluid-ordered-collection.ConsensusStack.md)

26
docs/get-started/README.md → docs/guide/README.md
Просмотреть файл

@ -2,36 +2,36 @@
uid: get-started
---
# Get Started
# Getting Started
If you are new to the Fluid Framework, we recommend reading [What is Fluid?](../what-is-fluid.md) to orient yourself.
The quickest way to get started with Fluid is to build a component. First, you'll need to clone the Fluid Framework
repository and install [yo fluid](xref:yo-fluid).
<a name="fluid-repo" />
repository and install [yo fluid](./yo-fluid.md).
## Clone the Fluid repo
The repository is located at <https://github.com/Microsoft/FluidFramework/>.
> [!IMPORTANT]
> To gain access to the repo you must be part of the Microsoft organization on GitHub. You can do that by following the
> steps provided at [https://repos.opensource.microsoft.com/link](https://repos.opensource.microsoft.com/link).
::: important
To gain access to the repo you must be part of the Microsoft organization on GitHub. You can do that by following the
steps provided at [https://repos.opensource.microsoft.com/link](https://repos.opensource.microsoft.com/link).
:::
After linking your accounts you should be added to the <https://github.com/orgs/Microsoft/teams/everyone> group which
will grant you access to the Fluid Framework repo. If for some reason you are not automatically added to that group
request to join at <https://repos.opensource.microsoft.com/Microsoft/teams/pragueread>.
## Install and run yo fluid
1. [Install and run yo fluid](xref:yo-fluid) to create a scaffold for your component, which you will build upon.
1. [Install and run yo fluid](./yo-fluid.md) to create a scaffold for your component, which you will build upon.
1. While implementing your component, you'll [use Fluid's local dev server to test your
component.](./build-a-component.md#development-process) The local dev server will use the Fluid team's hosted Fluid
service, called <xref:r11s>.
component.](./build-a-component.md#development-process)
1. Once you're ready to share your component, you'll [publish it to
Verdaccio,](./build-a-component.md#publish-your-package) the Fluid team's local NPM repository.
1. You can [use the Fluid Water Park](xref:water-park) to load any Fluid component from Verdaccio, including your own.
1. You can [use the Fluid Water Park](./water-park.md) to load any Fluid component from Verdaccio, including your own.
## Useful stuff
The Fluid packages are published to our [private NPM feed](xref:package-feed)
The Fluid packages are published to our [private NPM feed](../misc/package-feed.md)

4
docs/get-started/SharedCell.md → docs/guide/SharedCell.md
Просмотреть файл

@ -4,8 +4,8 @@ uid: SharedCell
# SharedCell
- Package: <xref:@microsoft/fluid-cell!>
- API documentation: <xref:@microsoft/fluid-cell!SharedCell:class>
- Package: [@microsoft/fluid-cell](../api/fluid-cell.md)
- API documentation: [SharedCell](../api/fluid-cell.SharedCell.md)
The SharedCell distributed data structure can be used to wrap an Object so that it can be used like a distributed data
structure.

69
docs/guide/SharedDirectory.md Normal file
Просмотреть файл

@ -0,0 +1,69 @@
---
uid: SharedDirectory
---
# SharedDirectory and IDirectory
- Package: [@microsoft/fluid-map](../api/fluid-map.md)
- API documentation:
- [SharedDirectory](../api/fluid-map.SharedDirectory.md)
- [IDirectory](../api/fluid-map.IDirectory.md)
The SharedDirectory distributed data structure is similar to a [SharedMap][] and can be used to store key-value pairs.
In addition to the typical Map functionality for getting, setting, and iterating over values, SharedDirectory provides a
hierarchical organization of map-like data structures as SubDirectories. The values stored within can be accessed like a
map, and the hierarchy can be navigated using path syntax. SubDirectories can be retrieved for use as working
directories. This subdirectory tree can be used to give hierarchical structure to stored key/value pairs rather than
storing them on a flat map. Both the `SharedDirectory` and any subdirectories are `IDirectories`. For example:
```ts
mySharedDirectory
.createSubDirectory("a")
.createSubDirectory("b")
.createSubDirectory("c")
.set("foo", val1);
const mySubDir = mySharedDirectory.getWorkingDirectory("/a/b/c");
mySubDir.get("foo"); // returns val1
```
It provides the same API for setting and
retrieving values that JavaScript developers are accustomed to with the
[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) built-in object.
## Creation
To create a `SharedDirectory`, call the static create method:
```typescript
const myDirectory = SharedDirectory.create(this.runtime, id);
```
## Usage
The map operations on an `IDirectory` refer to the key/value pairs stored in that `IDirectory`, and function just like
[SharedMap][] including the same restrictions on keys and values. To operate on the subdirectory structure, use the
corresponding subdirectory methods.
### getWorkingDirectory
To "navigate" the subdirectory structure, `IDirectory` provides a
[getWorkingDirectory](../api/fluid-map.SharedDirectory.getWorkingDirectory.md) method which takes a relative path and
returns the `IDirectory` located at that path if it exists.
!!!include(object-serialization.md)!!!
SharedDirectory keys are _last write wins_; this behavior works well with few infrequent writers and many readers. In cases
with many frequent writers it's best to design your use of the directory such that each writer writes to its own keys so
they don't overwrite each other.
## Eventing
[valueChanged](../api/fluid-map.SharedDirectory.on_1.md) events additionally provide the absolute path to the
subdirectory storing the value that changed.
## Related distributed data structures
- [SharedMap][]
<!-- Links -->
[SharedMap]: ./SharedMap.md

26
docs/get-started/SharedMap.md → docs/guide/SharedMap.md
Просмотреть файл

@ -4,8 +4,10 @@ uid: SharedMap
# SharedMap
- Package: <xref:@microsoft/fluid-map!>
- API documentation: <xref:@microsoft/fluid-map!SharedMap:class>
- Package: [@microsoft/fluid-map](../api/fluid-map.md)
- API documentation:
- [SharedMap](../api/fluid-map.SharedMap.md)
- [ISharedMap](../api/fluid-map.ISharedMap.md)
The SharedMap distributed data structure can be used to store key-value pairs. It provides the same API for setting and
retrieving values that JavaScript developers are accustomed to with the
@ -25,14 +27,14 @@ Unlike JavaScript Maps, a SharedMap's keys must be strings. The value must only
handles, or value types., including another distributed data structure. Thus, you can use nested SharedMaps and other
distributed data structures to construct a Fluid data model.
[!INCLUDE [object-serialization](../includes/object-serialization.md)]
!!!include(object-serialization.md)!!!
SharedMap keys are _last write wins_; this behavior works well with few infrequent writers and many readers. In cases
with many frequent writers it's best to design your use of the map such that each writer writes to its own keys/maps, so
they don't overwrite each other.
`SharedMap` has a <xref:@microsoft/fluid-map!SharedMap%23wait:member(1)> method in addition to the normal
<xref:@microsoft/fluid-map!SharedMap%23get:member(1)>, which returns a `Promise` that resolves to the value when the key becomes
`SharedMap` has a [wait](../api/fluid-map.SharedMap.wait.md) method in addition to the normal
[get](../api/fluid-map.SharedMap.get.md), which returns a `Promise` that resolves to the value when the key becomes
available.
### Eventing
@ -40,12 +42,18 @@ available.
`SharedMap` is an `EventEmitter`, and will emit events when other clients make modifications. You should register for
these events and respond appropriately as the data is modified.
[valueChanged](<xref:@microsoft/fluid-map!SharedMap%23on:member(2)>) will be emitted in response to a
<xref:@microsoft/fluid-map!SharedMap%23set:member(1)>, <xref:@microsoft/fluid-map!SharedMap%23delete:member(1)> and
[valueChanged](../api/fluid-map.SharedMap.on_1.md) will be emitted in response to a
[set](../api/fluid-map.SharedMap.set.md) or [delete](../api/fluid-map.SharedMap.delete.md) and
provide the key and previous value that was stored at that key.
`clear` will be emitted in response to <xref:@microsoft/fluid-map!SharedMap%23clear:member(1)>.
`clear` will be emitted in response to [clear](../api/fluid-map.SharedMap.clear.md).
## Examples using SharedMap
[Sudoku](../examples/sudoku.md)
## Related distributed data structures
- <xref:SharedDirectory>
- [SharedDirectory][]
[SharedDirectory]: ./SharedDirectory.md

26
docs/guide/SharedNumberSequence.md Normal file
Просмотреть файл

@ -0,0 +1,26 @@
---
uid: SharedNumberSequence
---
# SharedNumberSequence
- Package: [@microsoft/fluid-sequence](../api/fluid-sequence.md)
- API documentation: [SharedNumberSequence](../api/fluid-sequence.SharedNumberSequence.md)
The SharedNumberSequence distributed data structure can be used to store sequences of numbers.
## Creation
To create a `SharedNumberSequence`, call the static create method:
```typescript
const mySequence = SharedNumberSequence.create(this.runtime, id);
```
!!!include(sequences-usage.md)!!!
## Related distributed data structures
- [SharedObjectSequence](./SharedObjectSequence.md)
- [SharedString](./SharedString.md)
- [SparseMatrix](./SparseMatrix.md)

26
docs/guide/SharedObjectSequence.md Normal file
Просмотреть файл

@ -0,0 +1,26 @@
---
uid: SharedObjectSequence
---
# SharedObjectSequence
- Package: [@microsoft/fluid-sequence](../api/fluid-sequence.md)
- API documentation: [SharedObjectSequence](../api/fluid-sequence.SharedObjectSequence.md)
The SharedObjectSequence distributed data structure can be used to store sequences of objects.
## Creation
To create a `SharedObjectSequence`, call the static create method:
```typescript
const mySequence = SharedObjectSequence.create(this.runtime, id);
```
!!!include(sequences-usage.md)!!!
## Related distributed data structures
- [SharedNumberSequence](./SharedNumberSequence.md)
- [SharedString](./SharedString.md)
- [SparseMatrix](./SparseMatrix.md)

17
docs/guide/SharedString.md Normal file
Просмотреть файл

@ -0,0 +1,17 @@
---
uid: SharedString
sidebarDepth: 2
---
# SharedString
- Package: [@microsoft/fluid-sequence](../api/fluid-sequence.md)
- API documentation: [SharedString](../api/fluid-sequence.SharedString.md)
!!!include(sequences-usage.md)!!!
## Related distributed data structures
- [SharedNumberSequence](./SharedNumberSequence.md)
- [SharedObjectSequence](./SharedObjectSequence.md)
- [SparseMatrix](./SparseMatrix.md)

17
docs/guide/SparseMatrix.md Normal file
Просмотреть файл

@ -0,0 +1,17 @@
---
uid: SparseMatrix
sidebarDepth: 2
---
# SparseMatrix
- Package: [@microsoft/fluid-sequence](../api/fluid-sequence.md)
- API documentation: [SparseMatrix](../api/fluid-sequence.SparseMatrix.md)
!!!include(sequences-usage.md)!!!
## Related distributed data structures
- [SharedNumberSequence](./SharedNumberSequence.md)
- [SharedObjectSequence](./SharedObjectSequence.md)
- [SharedString](./SharedString.md)

23
docs/get-started/build-a-component.md → docs/guide/build-a-component.md
Просмотреть файл

@ -4,12 +4,13 @@ uid: build-a-component
# Build a component
> [!WARNING]
> This documentation is based on an earlier version of the Fluid Framework and is outdated.
>
> Track the documentation update with [#641](https://github.com/microsoft/FluidFramework/issues/641).
::: warning
This documentation is based on an earlier version of the Fluid Framework and is outdated.
If you haven't already, you should [install and run yo fluid](xref:yo-fluid) and use it to generate scaffolding for a
Track the documentation update with [#641](https://github.com/microsoft/FluidFramework/issues/641).
:::
If you haven't already, you should [install and run yo fluid](./yo-fluid.md) and use it to generate scaffolding for a
new component.
Within your project folder you can use the following commands:
@ -25,7 +26,8 @@ Within your project folder you can use the following commands:
## Development process
While you're developing your component, you can test and debug your code locally using `npm start`. This will load your
component code from a local web server, but will use the Fluid team's hosted Fluid server, <xref:r11s>, as the Fluid server.
component code from a local web server, but will use the Fluid team's hosted Fluid server,
[Routerlicious](../architecture/server/), as the Fluid server.
## Sharing your component
@ -37,9 +39,12 @@ package, build it, and publish the result to Verdaccio. It will also provide you
`https://www.wu2-ppe.prague.office-int.com/waterpark?chaincode=@chaincode/<your-package>`, which
you can use to load your component into the Water Park.
> [!TIP]
> This is a spiritual equivalent to publishing to npmjs.org
::: tip
This is a spiritual equivalent to publishing to npmjs.org
:::
### Load your component in the Water Park
See <xref:water-park>
See [the Water Park docs](./water-park.md).

16
docs/guide/consensus.md Normal file
Просмотреть файл

@ -0,0 +1,16 @@
# Consensus data structures
## ConsensusQueue
- Package: [@microsoft/fluid-ordered-collection](../api/fluid-ordered-collection.md)
- API documentation: [ConsensusQueue](../api/fluid-ordered-collection.ConsensusQueue.md)
## ConsensusRegisterCollection
- Package: [@microsoft/fluid-register-collection](../api/fluid-register-collection.md)
- API documentation: [ConsensusRegisterCollection](../api/fluid-register-collection.ConsensusRegisterCollection.md)
## ConsensusStack
- Package: [@microsoft/fluid-ordered-collection](../api/fluid-ordered-collection.md)
- API documentation: [ConsensusStack](../api/fluid-ordered-collection.ConsensusStack.md)

0
docs/advanced/dds-anatomy.md → docs/guide/dds-anatomy.md
Просмотреть файл

41
docs/guide/dds.md Normal file
Просмотреть файл

@ -0,0 +1,41 @@
---
uid: dds
---
# Distributed Data Structures
Much of Fluid's power lies in a set of base primitives called distributed data structures. These data structures, such
as such as [SharedMap](./SharedMap.md) and the various types in the @microsoft/fluid-sequence package, are eventually
consistent. The Fluid runtime manages these data structures; as changes are made locally and remotely, they are merged
in seamlessly by the runtime.
When you're working with a DDS, you can largely treat it as a local object. You can make changes to it as needed.
However, this local object can be changed not only by your local code, but also by the Fluid runtime. The Fluid runtime
is responsible for inbounding changes from the server and then replaying those changes locally. This means your code
should be structured to react to changes to the DDS instances and update accordingly.
As you make changes to the local DDS instance, the changes are sent to the Fluid server. Other clients are notified of
the change -- or they can query the server for changes -- and then merge the changes in locally. All of this is managed
by the Fluid runtime.
The quality of eventual consistency improves performance because local changes can be made optimistically, knowing that
the runtime will merge the change in the appropriate way eventually. This is a guarantee made by the Fluid runtime.
Thus, you need not check for changes prior to 'committing' local changes. If there are changes on the server, they will
be retrieved and merged in seamlessly, and events will be emitted by the data structures, allowing your code to react to
the changes if needed. And this all happens _very_ quickly.
::: tip
To avoid UI jitter when inbounding a lot of changes, consider just rendering based on frames per second, rather than on
data inbound. At data inbound you can invalidate portions of the UI to re-render when you render next. This decoupling
rendering from data inbound should reduce UI jitter.
:::
There are cases, however, where the eventually consistent guarantee is insufficient. In these cases, the consensus data
structures are useful. These types of data structures defer applying operations until they're acknowledged by the
server. This ensures that each client .pops() a different value from a stack, for example.
<!-- The content for this section will come from this [source document][1].
[1]: https://microsoft.sharepoint.com/:w:/t/Prague/EbN0Q0YfRpxLhvu71KvtpacBWAUoOm88XDRXd_p-6GfmfQ?e=3DckiM
<iframe src="https://microsoft.sharepoint.com/teams/Prague/_layouts/15/Doc.aspx?sourcedoc={464374b3-461f-4b9c-86fb-bbd4abeda5a7}&amp;action=embedview&amp;wdStartOn=1" width="695px" height="1000px" frameborder="0">This is an embedded <a target="_blank" href="https://office.com">Microsoft Office</a> document, powered by <a target="_blank" href="https://office.com/webapps">Office</a>.</iframe> -->

7
docs/guide/sequences.md Normal file
Просмотреть файл

@ -0,0 +1,7 @@
---
title: Sequences primer
---
!!!include(../../packages/runtime/sequence/readme.md)!!!
_From <https://github.com/microsoft/FluidFramework/blob/master/packages/runtime/sequence/readme.md>._

17
docs/guide/water-park.md Normal file
Просмотреть файл

@ -0,0 +1,17 @@
---
uid: water-park
---
# The Component Water Park
::: warning
This documentation is based on an earlier version of the Fluid Framework and is outdated.
Track the documentation update with [#104](https://github.com/microsoft/FluidFramework/issues/104).
:::
The Fluid Component Water Park is a place to explore, test, and share components. It can load any component made with
[yo fluid](./yo-fluid.md) and published to Verdaccio. `yo fluid` provides instructions on how to publish your components to
Verdaccio.
[Visit the Water Park](https://aka.ms/fluidwaterpark) to get started.

45
docs/guide/yo-fluid.md Normal file
Просмотреть файл

@ -0,0 +1,45 @@
---
uid: yo-fluid
---
# yo fluid
yo fluid is a tool that helps create a scaffold for a Fluid component.
First, [clone the Fluid Framework repo locally](./README.md#clone-the-fluid-repo).
Once you've cloned the repo, you can set up the `yo fluid` bootstrapper:
```
npm install -g yo
cd /FluidFramework/tools/generator-fluid
npm install
npm link
```
This will install yo fluid along with its dependency, [Yeoman](https://yeoman.io/).
Yo fluid is now ready. Use it to scaffold a new component by typing `yo fluid` and following the instructions.
::: tip
If you get an error when running `yo fluid` saying that a generator cannot be found, try using `yo @microsoft/fluid` instead.
:::
::: tip
For yo fluid setup issues see [this question on Microsoft Stack
Overflow](https://stackoverflow.microsoft.com/questions/137930/npm-install-fails-with-auth-issues/137931#137931)
:::
## Next steps
Now that you've used yo fluid to scaffold a new component, you should examine the contents of the yo fluid output, which
is a sample component called DiceRoller. See the [yo fluid breakdown](../examples/yo-fluid-breakdown.md) for a
step-by-step explanation of the code.
Or you can jump right in to [building your own component](./build-a-component.md) using the scaffold as a base.
## Source code
The source code for the yo fluid generator can be found at
<https://github.com/Microsoft/FluidFramework/blob/master/tools/generator-fluid/>.

3
docs/how/README.md Normal file
Просмотреть файл

@ -0,0 +1,3 @@
# How Fluid works
##

0
docs/get-started/developer-guide.md → docs/how/developer-guide.md
Просмотреть файл

0
docs/get-started/tob.md → docs/how/tob.md
Просмотреть файл

11
docs/includes/object-serialization.md
Просмотреть файл

@ -1,4 +1,7 @@
> [!NOTE]
> When using JavaScript objects with distributed data structures, the object must be safely JSON-serializable
> because the Fluid runtime will broadcast the object to other clients by serializing it. The client receiving the
> operation will deserialize it.
::: note
When using JavaScript objects with distributed data structures, the object must be safely JSON-serializable
because the Fluid runtime will broadcast the object to other clients by serializing it. The client receiving the
operation will deserialize it.
:::

11
docs/includes/sequences-usage.md Normal file
Просмотреть файл

@ -0,0 +1,11 @@
## Usage
Like all SharedSequences, you can use the [insert](../api/fluid-sequence.SharedSequence.insert.md) and
[getItems](../api/fluid-sequence.SharedSequence.getItems.md) methods to insert and retrieve items from the
sequence, and [remove](../api/fluid-sequence.SharedSequence.remove.md) to remove items.
## Eventing
Whenever an operation is performed on a sequence a [sequenceDelta](../api/fluid-sequence.SequenceDeltaEvent.md) event
will be raised. This event provides the ranges affected by the operation, the type of the operation, and the properties
that were changed by the operation.

53
docs/index.md
Просмотреть файл

@ -1,53 +0,0 @@
> [!CAUTION]
> This documentation is a work in progress.
> [!TIP]
> The URL to this documentation is <https://aka.ms/fluid>.
# Fluid
Welcome to Fluid!
We built Fluid to make it simpler for developers to build real-time collaborative experiences using Web technology.
Fluid enables distributed, collaborative applications by providing developers with eventually consistent <xref:dds>, a
flexible component and app model, and a reference server implementation called [Routerlicious](xref:r11s).
Teams across Microsoft are using Fluid for low latency collaboration, zero setup data persistence, and on-by-default
cross app compatibility. Among other projects, our partner teams are building components for text editing, gaming,
command line tooling, and IOT.
Fluid's [distributed data structures](xref:dds) make it easy to write apps that are collaborative just like you would build
single-user applications and experiences. Fluid handles keeping your data in sync across multiple clients, so you can
focus on your app's business logic. Fluid's data synchronization is fast, efficient, and requires very little
bandwidth. Fluid is extensible, too. You can write components which can be re-used or you can even create new
distributed data structures.
> [!TIP]
> Prague was the code name for the Fluid Framework. Fluid is the name we'll use going forward.
>
> `"Prague" === "Fluid" === "Fluid Framework"`
## What is Fluid?
See [this draft document](xref:what-is-fluid) for some more information about Fluid.
## Get started now
Get up and running quickly using our [Getting Started guide](xref:get-started).
## Help
### Stack Overflow
The Fluid team answers **questions** on the [Microsoft Stack Overflow](https://stackoverflow.microsoft.com/) using
the [Fluid](https://stackoverflow.microsoft.com/questions/tagged/fluid) tag.
Bugs, suggestions, and issues should be directed to our [issues page](https://github.com/Microsoft/FluidFramework/issues).
Logistical questions can be directed to our [Teams group](https://teams.microsoft.com/l/team/19%3a10ccb94cae324ec2aabcd6b6322b1a25%40thread.skype/conversations?groupId=9ce27575-2f82-4689-abdb-bcff07e8063b&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47).

6
docs/get-started/concepts.md → docs/misc/concepts.md
Просмотреть файл

@ -1,8 +1,4 @@
---
uid: concepts
---
# Concepts
# Glossary
* This section will contain deeper information about the key concepts that developers should understand to be effective
with Fluid.

4
docs/get-started/package-feed.md → docs/misc/package-feed.md
Просмотреть файл

@ -16,7 +16,7 @@ Prerequisites: [Node (with npm)](https://nodejs.org) installed
2. Add registry to our scopes (globally per-user)
```text
```
npm config set @microsoft:registry https://offnet.pkgs.visualstudio.com/_packaging/prague/npm/registry/
npm config set @fluid-example:registry https://offnet.pkgs.visualstudio.com/_packaging/prague/npm/registry/
npm config set @fluid-internal:registry https://offnet.pkgs.visualstudio.com/_packaging/prague/npm/registry/
@ -38,7 +38,7 @@ Prerequisites: [Node (with npm)](https://nodejs.org) installed
* You can add the registry setting to your project only instead of globally.
Just add the follow to your `.npmrc` in the root of your NPM package:
```text
```
@microsoft:registry=https://offnet.pkgs.visualstudio.com/_packaging/prague/npm/registry/
@fluid-example:registry=https://offnet.pkgs.visualstudio.com/_packaging/prague/npm/registry/
@fluid-internal:registry=https://offnet.pkgs.visualstudio.com/_packaging/prague/npm/registry/

8
docs/get-started/terminology.md → docs/misc/terminology.md
Просмотреть файл

@ -6,13 +6,13 @@ uid: terminology
## Component
See [Components](xref:concepts#components)
See [Components](./concepts.md#components)
## Component Host
## Container
See [Containers](xref:concepts#containers)
See [Containers](./concepts.md#containers)
## Driver
@ -24,7 +24,7 @@ See <https://github.com/microsoft/FluidFramework/blob/master/samples/hosts/liter
## Routerlicious
See <xref:r11s>
See [Routerlicious](../architecture/server/README.md).
## Sequence Number
@ -34,7 +34,7 @@ See <xref:r11s>
## Snapshots
See [Summary ops](xref:terminology#summary-ops)
See [Summary ops](#summary-ops)
## Summary ops

9196
docs/package-lock.json сгенерированный Normal file
Просмотреть файл

Разница между файлами не показана из-за своего большого размера Загрузить разницу

33
docs/package.json Normal file
Просмотреть файл

@ -0,0 +1,33 @@
{
"name": "fluid-docs",
"version": "0.13.0",
"description": "Documentation for the Fluid Framework",
"license": "MIT",
"author": "Microsoft",
"scripts": {
"build": "npm run build:vuepress",
"build:ci": "npm run build:copy && node buildDocs.js && npm run build:vuepress",
"build:copy": "copyfiles -f \"api-pages/**\" api/",
"build:vuepress": "vuepress build --dest ./dist",
"clean": "rimraf api",
"lint": "vuepress check-md",
"start": "npm run build:copy && node buildDocs.js && vuepress dev",
"test": "echo \"Error: no test specified\" && exit 1"
},
"dependencies": {
"copyfiles": "^2.1.0",
"firstline": "^2.0.2",
"fs-extra": "^8.1.0",
"markdown-it-deflist": "^2.0.3",
"markdown-it-include": "^1.1.0",
"vue-tabs-component": "^1.5.0",
"vuepress": "1.2.0",
"vuepress-plugin-check-md": "0.0.2",
"vuepress-plugin-code-copy": "^1.0.4",
"vuepress-plugin-container": "^2.1.2",
"vuepress-plugin-tabs": "^0.3.0"
},
"devDependencies": {
"rimraf": "^2.6.2"
}
}

89
docs/templates/fluid/UniversalReference.extension.js поставляемый
Просмотреть файл

@ -1,89 +0,0 @@
// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
/**
* This method will be called at the start of exports.transform in UniversalReference.html.primary.js
*/
exports.preTransform = function (model) {
return model;
}
/**
* This method will be called at the end of exports.transform in UniversalReference.html.primary.js
*/
exports.postTransform = function (model) {
// The model is the data in the yml file after the default transform done by UniversalReference.common.js in the default template
// The default template can be viewed via "docfx template export default" command
if (model.isClass && model.children) {
// Split the properties and method group into protected/static groups
const children = [];
const protectedChildren = [];
model.children.forEach(function (c) {
if (c.inMethod && c.children) {
stripVoidReturn(c.children);
splitProtectStatic(children, protectedChildren, c, "Method", "methods");
} else if (c.inProperty && c.children) {
splitProtectStatic(children, protectedChildren, c, "Property", "properties");
} else {
children.push(c);
}
});
model.children = children.concat(protectedChildren)
}
return model;
}
function stripVoidReturn(children) {
// If the return type is void, remove it so that it doesn't show up
children.forEach(function (m) {
try {
if (m.syntax.return[0].value.type[0].uid === "void") {
m.syntax.return = undefined;
}
} catch (e) {
}
});
}
function initGroup(prefix, name, idPrefix, idName) {
const group = {};
const inName = "in" + prefix + name;
const id = idPrefix ? idPrefix + "_" + idName : idName
group[inName] = true;
group.typePropertyName = inName;
group.id = id;
group.children = [];
return group;
}
function splitProtectStatic(children, protectedChildren, c, name, idName) {
const group = initGroup("", name, undefined, idName);
const protectedGroup = initGroup("Protected", name, "protected", idName);
const staticGroup = initGroup("Static", name, "static", idName);
const protectedStaticGroup = initGroup("ProtectedStatic", name, "protected_static", idName);
c.children.forEach(function (m) {
const name = m.syntax && m.syntax.content && m.syntax.content[0]
&& m.syntax.content[0].value ? m.syntax.content[0].value : ""
if (name.indexOf("protected static ") === 0) {
protectedStaticGroup.children.push(m);
} else if (name.indexOf("protected ") === 0) {
protectedGroup.children.push(m);
} else if (name.indexOf("static ") === 0) {
staticGroup.children.push(m);
} else {
group.children.push(m);
}
});
if (staticGroup.children.length > 0) {
children.push(staticGroup);
}
if (group.children.length > 0) {
children.push(group);
}
if (protectedStaticGroup.children.length > 0) {
protectedChildren.push(protectedStaticGroup);
}
if (protectedGroup.children.length > 0) {
protectedChildren.push(protectedGroup);
}
}

40
docs/templates/fluid/partials/classSubtitle.tmpl.partial поставляемый
Просмотреть файл

@ -1,40 +0,0 @@
{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
{{#inConstructor}}
{{__global.constructorsInSubtitle}}
{{/inConstructor}}
{{#inField}}
{{__global.fieldsInSubtitle}}
{{/inField}}
{{#inProperty}}
{{__global.propertiesInSubtitle}}
{{/inProperty}}
{{#inStaticMethod}}
Static Methods
{{/inStaticMethod}}
{{#inMethod}}
{{__global.methodsInSubtitle}}
{{/inMethod}}
{{#inProtectedProperty}}
Protected Properties
{{/inProtectedProperty}}
{{#inProtectedStaticMethod}}
Protected Static Methods
{{/inProtectedStaticMethod}}
{{#inProtectedMethod}}
Protected Methods
{{/inProtectedMethod}}
{{#inEvent}}
{{__global.eventsInSubtitle}}
{{/inEvent}}
{{#inOperator}}
{{__global.operatorsInSubtitle}}
{{/inOperator}}
{{#inEii}}
{{__global.eiisInSubtitle}}
{{/inEii}}
{{#inFunction}}
{{__global.functionsInSubtitle}}
{{/inFunction}}
{{#inMember}}
{{__global.membersInSubtitle}}
{{/inMember}}

67
docs/templates/fluid/partials/uref/class.header.tmpl.partial поставляемый
Просмотреть файл

@ -1,67 +0,0 @@
{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
<h1 id="{{id}}" data-uid="{{uid}}">{{>partials/title}}</h1>
{{#package}}
<div class="package attributes">
<span class="package-label">Package: </span>{{{package}}}</div>
{{/package}}
{{#extends.0}}
<div class="extends attributes">
<span class="extends-label">Extends: </span>
{{/extends.0}}
{{#extends}}
<xref uid="{{.}}" altProperty="fullName" displayProperty="name"/>
{{/extends}}
{{#extends.0}}
</div>
{{/extends.0}}
{{#implements.0}}
<div class="implements attributes">
<span class="implements-label">Implements: </span>
{{/implements.0}}
{{#implements}}
{{{value.0.specName.0.value}}}
{{/implements}}
{{#implements.0}}
</div>
{{/implements.0}}
<div class="markdown level0 summary">{{{summary}}}</div>
<div class="markdown level0 conceptual">{{{conceptual}}}</div>
{{#inheritance.0}}
<div class="inheritance">
<h5>{{__global.inheritance}}</h5>
{{/inheritance.0}}
{{#inheritance}}
<div class="level{{index}}">{{{specName.0.value}}}</div>
{{/inheritance}}
{{#inheritance.0}}
<div class="level{{item.level}}"><span class="xref">{{item.name.0.value}}</span></div>
</div>
{{/inheritance.0}}
{{#inheritedMembers.0}}
<div class="inheritedMembers">
<h5>{{__global.inheritedMembers}}</h5>
{{/inheritedMembers.0}}
{{#inheritedMembers}}
<div>
{{#definition}}
<xref uid="{{definition}}" altProperty="fullName" displayProperty="name"/>
{{/definition}}
{{^definition}}
<xref uid="{{uid}}" altProperty="fullName" displayProperty="name"/>
{{/definition}}
</div>
{{/inheritedMembers}}
{{#inheritedMembers.0}}
</div>
{{/inheritedMembers.0}}
{{#remarks}}
<h5 id="{{id}}_remarks"><strong>{{__global.remarks}}</strong></h5>
<div class="markdown level0 remarks">{{{remarks}}}</div>
{{/remarks}}
{{#example.0}}
<h5 id="{{id}}_examples"><strong>{{__global.examples}}</strong></h5>
{{/example.0}}
{{#example}}
{{{.}}}
{{/example}}

255
docs/templates/fluid/partials/uref/class.tmpl.partial поставляемый
Просмотреть файл

@ -1,255 +0,0 @@
{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
{{>partials/uref/class.header}}
{{#children}}
<h3 id="{{id}}">{{>partials/classSubtitle}}</h3>
<table class="table table-bordered table-striped table-condensed">
<thead>
<tr>
<th>{{__global.name}}</th>
<th>{{__global.description}}</th>
</tr>
</thead>
<tbody>
{{#children}}
<tr>
<td><xref uid="{{uid}}">{{name.0.value}}</xref></td>
<td class="table-description">{{{summary}}}</td>
</tr>
{{/children}}
</tbody>
</table>
{{/children}}
{{#children}}
<h3 id="{{id}}_details">{{>partials/classSubtitle}} Details</h3>
{{#children}}
{{^_disableContribution}}
{{#docurl}}
<span class="small pull-right mobile-hide">
<span class="divider">|</span>
<a href="{{docurl}}">{{__global.improveThisDoc}}</a>
</span>{{/docurl}}
{{#sourceurl}}
<span class="small pull-right mobile-hide">
<a href="{{sourceurl}}">{{__global.viewSource}}</a>
</span>{{/sourceurl}}
{{/_disableContribution}}
{{#overload}}
<a id="{{id}}" data-uid="{{uid}}"></a>
{{/overload}}
<h4 id="{{id}}" data-uid="{{uid}}">{{name.0.value}}</h4>
<div class="markdown level1 summary">{{{summary}}}</div>
<div class="markdown level1 conceptual">{{{conceptual}}}</div>
<h5 class="declaration">{{__global.declaration}}</h5>
{{#syntax}}
<div class="codewrapper">
<pre><code class="lang-{{syntax.content.0.lang}} hljs">{{syntax.content.0.value}}</code></pre>
</div>
{{#parameters.0}}
<h5 class="parameters">{{__global.parameters}}</h5>
<table class="table table-bordered table-striped table-condensed">
<thead>
<tr>
<th>{{__global.type}}</th>
<th>{{__global.name}}</th>
<th>{{__global.description}}</th>
</tr>
</thead>
<tbody>
{{/parameters.0}}
{{#parameters}}
<tr>
<td class="table-type-name">{{{type.specName.0.value}}}</td>
<td class="table-param-name"><em>{{{id}}}</em></td>
<td class="table-description">
{{{description}}}
{{>partials/uref/parameters}}
</td>
</tr>
{{/parameters}}
{{#parameters.0}}
</tbody>
</table>
{{/parameters.0}}
{{#return}}
<h5 class="returns">{{__global.returns}}</h5>
<table class="table table-bordered table-striped table-condensed">
<thead>
<tr>
<th>{{__global.type}}</th>
<th>{{__global.description}}</th>
</tr>
</thead>
<tbody>
<tr>
<td class="table-type-name">{{{value.type.0.specName.0.value}}}</td>
<td class="table-description">{{{value.description}}}</td>
</tr>
</tbody>
</table>
{{/return}}
{{#typeParameters.0}}
<h5 class="typeParameters">{{__global.typeParameters}}</h5>
<table class="table table-bordered table-striped table-condensed">
<thead>
<tr>
<th>{{__global.name}}</th>
<th>{{__global.description}}</th>
</tr>
</thead>
<tbody>
{{/typeParameters.0}}
{{#typeParameters}}
<tr>
<td><em>{{{id}}}</em></td>
<td>{{{description}}}</td>
</tr>
{{/typeParameters}}
{{#typeParameters.0}}
</tbody>
</table>
{{/typeParameters.0}}
{{#fieldValue}}
<h5 class="fieldValue">{{__global.fieldValue}}</h5>
<table class="table table-bordered table-striped table-condensed">
<thead>
<tr>
<th>{{__global.type}}</th>
<th>{{__global.description}}</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{{value.type.0.specName.0.value}}}</td>
<td>{{{value.description}}}</td>
</tr>
</tbody>
</table>
{{/fieldValue}}
{{#propertyValue}}
<h5 class="propertyValue">{{__global.propertyValue}}</h5>
<table class="table table-bordered table-striped table-condensed">
<thead>
<tr>
<th>{{__global.type}}</th>
<th>{{__global.description}}</th>
</tr>
</thead>
<tbody>
<tr>
<td class="table-type-name">{{{value.type.0.specName.0.value}}}</td>
<td class="table-description">{{{value.description}}}</td>
</tr>
</tbody>
</table>
{{/propertyValue}}
{{#eventType}}
<h5 class="eventType">{{__global.eventType}}</h5>
<table class="table table-bordered table-striped table-condensed">
<thead>
<tr>
<th>{{__global.type}}</th>
<th>{{__global.description}}</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{{type.specName.0.value}}}</td>
<td>{{{description}}}</td>
</tr>
</tbody>
</table>
{{/eventType}}
{{/syntax}}
{{#overridden}}
<h5 class="overrides">{{__global.overrides}}</h5>
<div><xref href="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/></div>
{{/overridden}}
{{#implements.0}}
<h5 class="implements">{{__global.implements}}</h5>
{{/implements.0}}
{{#implements}}
{{#definition}}
<div><xref href="{{definition}}" altProperty="fullName" displayProperty="nameWithType"/></div>
{{/definition}}
{{^definition}}
<div><xref href="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/></div>
{{/definition}}
{{/implements}}
{{#remarks}}
<h5 id="{{id}}_remarks">{{__global.remarks}}</h5>
<div class="markdown level1 remarks">{{{remarks}}}</div>
{{/remarks}}
{{#example.0}}
<h5 id="{{id}}_examples">{{__global.examples}}</h5>
{{/example.0}}
{{#example}}
{{{.}}}
{{/example}}
{{#exceptions.0}}
<h5 class="exceptions">{{__global.exceptions}}</h5>
<table class="table table-bordered table-striped table-condensed">
<thead>
<tr>
<th>{{__global.type}}</th>
<th>{{__global.condition}}</th>
</tr>
</thead>
<tbody>
{{/exceptions.0}}
{{#exceptions.0.value}}
<tr>
<td>{{{type.specName.0.value}}}</td>
<td>{{{description}}}</td>
</tr>
{{/exceptions.0.value}}
{{#exceptions.0}}
</tbody>
</table>
{{/exceptions.0}}
{{#seealso.0}}
<h5 id="{{id}}_seealso">{{__global.seealso}}</h5>
<div class="seealso">
{{/seealso.0}}
{{#seealso}}
{{#isCref}}
<div>{{{type.specName.0.value}}}</div>
{{/isCref}}
{{^isCref}}
<div>{{{url}}}</div>
{{/isCref}}
{{/seealso}}
{{#seealso.0}}
</div>
{{/seealso.0}}
{{/children}}
{{/children}}
{{#extensionMethods.0}}
<h3 id="extensionmethods">{{__global.extensionMethods}}</h3>
{{/extensionMethods.0}}
{{#extensionMethods}}
<div>
{{#definition}}
<xref href="{{definition}}" altProperty="fullName" displayProperty="nameWithType"/>
{{/definition}}
{{^definition}}
<xref href="{{uid}}" altProperty="fullName" displayProperty="nameWithType"/>
{{/definition}}
</div>
{{/extensionMethods}}
{{#seealso.0}}
<h3 id="seealso">{{__global.seealso}}</h3>
<div class="seealso">
{{/seealso.0}}
{{#seealso}}
{{#isCref}}
<div>{{{type.specName.0.value}}}</div>
{{/isCref}}
{{^isCref}}
<div>{{{url}}}</div>
{{/isCref}}
{{/seealso}}
{{#seealso.0}}
</div>
{{/seealso.0}}

14
docs/templates/fluid/styles/main.css поставляемый
Просмотреть файл

@ -1,14 +0,0 @@
div.attributes {
color: #949494
}
div.summary {
margin-top:20px;
}
td.table-param-name {
width: 12%;
}
td.table-description {
width: 60%;
}

99
docs/templates/fluid/toc.extension.js поставляемый
Просмотреть файл

@ -1,99 +0,0 @@
// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
var packageMapping = {
"fluid-component-runtime": "runtime",
"fluid-container-runtime": "runtime",
"fluid-runtime-definitions": "runtime",
"fluid-cell": "dds",
"fluid-ink": "dds",
"fluid-map": "dds",
"fluid-merge-tree": "dds",
"fluid-ordered-collection": "dds",
"fluid-register-collection": "dds",
"fluid-sequence": "dds",
"fluid-shared-object-base": "dds",
"fluid-stream": "dds",
"fluid-aqueduct-react": "framework",
"fluid-aqueduct": "framework",
"fluid-component-core-interfaces": "framework",
"fluid-framework-definitions": "framework",
"fluid-framework-interfaces": "framework",
"fluid-undo-redo": "framework",
"fluid-container-definitions": "loader",
"fluid-container-loader": "loader",
"fluid-execution-context-loader": "loader",
"fluid-protocol-definitions": "loader",
"fluid-web-code-loader": "loader",
"fluid-driver-base": "driver",
"fluid-driver-definitions": "driver",
"fluid-file-driver": "driver",
"fluid-iframe-driver": "driver",
"fluid-odsp-driver": "driver",
"fluid-replay-driver": "driver",
"fluid-routerlicious-driver": "driver",
"fluid-base-host": "host",
"react-web-host": "host",
"tiny-web-host": "host",
"fluid-debugger": "tools",
"fluid-merge-tree-client-replay": "tools",
"fluid-replay-tool": "tools",
"fluid-core-utils": "misc",
}
var groupNames = {
framework: "Framework",
dds: "Distributed Data Structures",
runtime: "Runtime",
loader: "Loader",
driver: "Driver",
host: "Sample Hosts",
tools: "Tools",
misc: "Misc",
unknown: "Internal/Deprecated",
};
/**
* This method will be called at the start of exports.transform in toc.html.js
*/
exports.preTransform = function (model) {
if (model.items && model.items.length > 0) {
if (model.items[0].name === "API overview") {
var overview = model.items[0];
var children = overview.items;
overview.items = undefined;
var groupedPackages = {};
for (var group in groupNames) {
groupedPackages[group] = [];
}
children.forEach(function (element) {
var group = packageMapping[element.name];
if (group === undefined || groupedPackages[group] === undefined) {
group = "unknown";
}
groupedPackages[group].push(element);
});
model.items = [overview];
for (var group in groupedPackages) {
model.items.push(
{ name: groupNames[group], items: groupedPackages[group] }
);
}
}
}
return model;
}
/**
* This method will be called at the end of exports.transform in toc.html.js
*/
exports.postTransform = function (model) {
return model;
}

21
docs/toc.yml
Просмотреть файл

@ -1,21 +0,0 @@
- name: Get Started
href: get-started/
topicHref: get-started/README.md
- name: Examples
href: examples/
topicHref: examples/README.md
- name: Architecture
href: architecture/
topicHref: architecture/README.md
- name: Tools
href: tools/
topicUid: tools
- name: Advanced Topics
href: advanced/
topicHref: advanced/README.md
- name: Contributing
href: contributing/
topicHref: contributing/README.md
- name: API Documentation
href: api/

8
docs/tools/toc.yml
Просмотреть файл

@ -1,8 +0,0 @@
- name: Tools
topicUid: tools
- name: Debugging
href: ../../packages/drivers/fluid-debugger/README.md
- name: Fluid Fetch
href: ../../packages/tools/fluid-fetch/README.md
- name: Replay Tool
href: ../../packages/tools/replay-tool/README.md

109
docs/what-is-fluid.md
Просмотреть файл

@ -1,12 +1,117 @@
---
uid: what-is-fluid
ms.topic: overview
sidebar: auto
---
# What is the Fluid Framework?
The content for this section will come from this [source document][1].
The Fluid Framework is a core developer technology and application platform for building a new class of shared,
interactive experiences on the Web. It will change the way people work through three core capabilities:
1. An innovative model for **distributed data** that will allow 'multi-person' real-time collaboration on Web and document
content at a speed and scale not yet achieved in the industry.
2. A **componentized document model** that allows authors to deconstruct content into collaborative building blocks,
**use them across applications**, and combine them in a new, more flexible kind of document.
3. Enabling intelligent agents to work alongside humans in ways that will dramatically increase productivity and what
people can accomplish
## What problems does the Fluid Framework address?
It is easiest to understand Fluid by examining the problems that it helps address. Namely, that it is challenging, with
the tools available today, to build collaborative experiences on the Web. A canonical example is co-authoring a document
or a presentation. A smaller example is the animated "typing..." indicator that is common in real-time chat apps (e.g.
Facebook, Slack, Teams).
Increasingly these collaborative experiences are "table stakes" for building Web-based experiences. However, despite
their importance, collaborative experiences can be difficult to build. It might be easy enough to show a "John is
typing" indicator since it has some simplifying constraints like the fact that the indicator is "read-only"; each client
can only write to the main chat stream and its own "typing" indicator.
But many practical scenarios, such as the canonical "co-authoring a document" scenario, involve more complex data that
is being updated by multiple clients, which increases complexity dramatically. Maintaining performance in such
situations is difficult. When multiple clients are manipulating the same data, it quickly becomes difficult to ensure
all clients are seeing the same consistent view of the data.
The way our industry-standard tools work today, if you want to build a collaborative experience – or more likely – add
some collaborative interactivity to an existing experience, you'll have to build quite a bit of infrastructure. For
example, you will likely need to use Web Sockets to keep clients updated quickly, you'll design a messaging protocol,
develop complex merge logic, you'll probably need a distributed cache, etc.
And you'll do this every time you need to build a collaborative experience, because the tools we use today are built for
a "one user at a time" world. Often you must build your collaborative experiences on top of foundations that aren't
themselves collaborative.
The Web is no longer a one user at a time world – if it ever was – and in order to build experiences that feel right for
the collaborative Web, we need tools that understand the collaborative world in which we live. It must become easier to
build and maintain these experiences to push the Web forward.
## Fluid Framework – Layered System
Fluid makes building collaborative experiences on the Web easier while simultaneously addressing the reasons many
collaborative experiences are poor. It addresses performance, complexity of working with distributed state,
componentization of data and UX, intelligent agents, and many other elements in modern applications.
Below is a diagram showing the full 'Fluid Tech Stack', followed by a description of each layer:
**TODO: Add diagram**
### Fluid Framework Distributed System - Total Order Broadcast & Eventual Consistency
Fluid is, at its core, a data model for distributed state. Building collaborative experiences boils down to managing
distributed state, and Fluid provides powerful developer-friendly abstractions for managing this state in the form of
distributed data structures. Each of these data structures is eventually consistent – this means that, assuming no new
changes to the data structures, all clients reach an identical state in a finite amount of time.
Fluid guarantees eventual consistency via total order broadcast. That is, when a Distributed Data Structure (DDS) is
changed locally by a client, that change – that is, the operation – is first sent to the Fluid server, which does three
things:
Assigns a monotonically increasing sequence number to the operation; this is the "total order" part of total order broadcast
Broadcasts the operation to all other connected clients; this is the "broadcast" part of total order broadcast
Stores the operation's data
This means that each client can apply every operation from the server to their local state in the same order, which in
turn means that each client will eventually be consistent with the client that originated the change.
The quality of eventual consistency improves performance because local changes can be made optimistically, knowing that
the Fluid runtime will merge the change in the appropriate way eventually. And because the system is operations-based,
it will be possible to build a wide range of capabilities including rich version history, attribution, data validation,
'time travel' within a document, and much more.
### Distributed Data Structures
Much of Fluid's power lies in a set of base primitives called distributed data structures. These data structures, such
as such as SharedMap and SharedString, are eventually consistent. The Fluid runtime manages these data structures; as
changes are made locally and remotely, they are merged in seamlessly by the runtime.
When you're working with a DDS, you can largely treat it as a local object. You can make changes to it as needed.
However, this local object can be changed not only by your local code, but also by the Fluid runtime. The Fluid runtime
is responsible for inbounding changes from the server and then replaying those changes locally. This means your code
should be structured to react to changes to the DDS instances and update accordingly.
As you make changes to the local DDS instance, the changes are sent to the Fluid server. Other clients are notified of
the change - or they can query the server for changes - and then merge the changes in locally. All of this is managed by
the Fluid runtime.
### Fluid Runtime and Component Model
Each client runs an instance of the Fluid Core, as illustrated in the diagram below.
The Fluid runtime is responsible for managing communication between the client and Fluid server and for applying
incoming operations. The runtime communicates with the Fluid server using Web Sockets, but you do not need to make any
network calls yourself in order to use Fluid. The runtime takes care of that for you.
### Fluid Component Model
On top of the runtime is a layered component model. A Fluid component can have a broad range of capabilities such as
distributed data, rendering, experience integration, and much more. For many developers their primary interaction with
Fluid will be writing components.
***
_[source document][1]_
[1]: https://microsoft.sharepoint.com/:w:/t/Prague/ESoVbMxYtoJKp1CqUUsycjYBuURKe1x3Bwgp4_2yCzrH3A?e=KeWZQd
<iframe src="https://microsoft.sharepoint.com/teams/Prague/_layouts/15/Doc.aspx?sourcedoc={cc6c152a-b658-4a82-a750-aa514b327236}&amp;action=embedview&amp;wdStartOn=1&amp;wdEmbedCode=0&amp;wdPrint=0" width="695px" height="1000px" frameborder="0">This is an embedded <a target="_blank" href="https://office.com">Microsoft Office</a> document, powered by <a target="_blank" href="https://office.com/webapps">Office</a>.</iframe>
<!-- <iframe src="https://microsoft.sharepoint.com/teams/Prague/_layouts/15/Doc.aspx?sourcedoc={cc6c152a-b658-4a82-a750-aa514b327236}&amp;action=embedview&amp;wdStartOn=1&amp;wdEmbedCode=0&amp;wdPrint=0" width="695px" height="1000px" frameborder="0">This is an embedded <a target="_blank" href="https://office.com">Microsoft Office</a> document, powered by <a target="_blank" href="https://office.com/webapps">Office</a>.</iframe> -->

2
package.json
Просмотреть файл

@ -11,7 +11,7 @@
"build:fast": "node ./tools/fluid-build/dist/fluidBuild.js --root .",
"build:full": "npm run build:genver && npm run build:full:compile && npm run tslint && npm run build:docs",
"build:full:compile": "lerna run build:full:compile --stream",
"build:gendocs": "api-documenter yaml -i packages/_api-extractor-temp/doc-models -o docs/api",
"build:gendocs": "api-documenter markdown -i packages/_api-extractor-temp/doc-models -o docs/api",
"build:genver": "lerna run build:genver --stream --parallel",
"bump-version": "lerna version minor --no-push --no-git-tag-version && npm run build:genver",
"clean": "lerna run clean --stream --parallel && npm run clean:docs && npm run clean:nyc",

2
packages/framework/aqueduct/src/components/blobHandle.ts
Просмотреть файл

@ -16,7 +16,7 @@ import { ISharedDirectory } from "@microsoft/fluid-map";
* This class represents blob (long string)
* This object is used only when creating (writing) new blob and serialization purposes.
* De-serialization process goes through ComponentHandle and request flow:
* PrimedComponent.request() recognizes requests in the form of '/blobs/<id>'
* PrimedComponent.request() recognizes requests in the form of `/blobs/<id>`
* and loads blob.
*/
export class BlobHandle implements IComponentHandle {